Skip to content

Commit d1282ce

Browse files
jhamonjhamon
authored
Implement docs with sphinx (#508)
## Problem Recent changes to implement lazy loading in the SDK have broken compatibility with our previous docs tool, pdoc. After some investigation, it seemed easier to adopt a new docs solution than to try to manipulate pdoc internals to work for our usecase. ## Solution - Implement configurations for docs in a new `docs` folder. Main points of interest: `docs/conf.py` and `docs/index.rst` - Adjust docstrings to use rst format throughout - Add a few custom styles in `docs/_static/custom.css` to tweak the look of the default sphinx theme which is using Garamond font and doesn't really match our branding at all. Changing up to use sans-serif fonts and tweaking a few other things gets us a long way there, although I'm sure there are still things to refine on that over time. - Build docs with `poetry run sphinx-build -b html docs docsbuild` - Implement some minor shenanigans to work around poetry and sphinx's rigidness about python version support. To do this in a nicer way I would either have to drop python 3.9 and 3.10 from our SDK's supported python versions, or setup a separate package outside this repo that depended on `sphinx` and the published `pinecone`. Neither one of those sound like good options to me. ## Type of Change - [x] New feature (non-breaking change which adds functionality) ## Testing New docs visible at https://sdk.pinecone.io/python I published these by manually triggering the build-and-publish-docs job from this branch
1 parent 9b85d0a commit d1282ce

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+3032
-2542
lines changed

‎.github/actions/build-docs/action.yml‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: 'Build client documentation'
2-
description: 'Generates client documentation using pdoc'
2+
description: 'Generates client documentation using sphinx'
33
inputs:
44
python-version:
55
description: 'Python version to use'
@@ -13,15 +13,31 @@ runs:
1313
with:
1414
include_grpc: 'true'
1515
include_dev: 'true'
16+
include_asyncio: 'true'
1617
python_version: ${{ inputs.python-version }}
18+
19+
- name: Pretend this project requires Python 3.11
20+
shell: bash
21+
run: |
22+
# Poetry won't let me install sphinx as a dev dependency in this project
23+
# because of the wide range of versions our library supports. So during this
24+
# action, we'll pretend this project requires Python 3.11 or greater.
25+
sed -i 's/python = "^3.9"/python = "^3.11"/' pyproject.toml
26+
poetry lock
27+
poetry install -E grpc -E asyncio
28+
29+
- name: Install sphinx
30+
shell: bash
31+
run: |
32+
poetry add sphinx myst-parser --group dev
33+
1734
- name: Build html documentation
1835
shell: bash
1936
run: |
20-
poetry run pdoc pinecone '!pinecone.core' '!pinecone.utils' --favicon ./favicon-32x32.png --docformat google -o ./pdoc
37+
poetry run sphinx-build -b html docs docsbuild
2138
22-
- name: Fix relative links
39+
- name: Discard changes to pyproject.toml and poetry.lock
2340
shell: bash
2441
run: |
25-
poetry run python3 ./.github/actions/build-docs/fix-relative-links.py ./pdoc ./pdoc
26-
env:
27-
BASE_URL: "https://github.com/pinecone-io/pinecone-python-client/blob/main/"
42+
git checkout pyproject.toml
43+
git checkout poetry.lock

‎.github/actions/build-docs/fix-relative-links.py‎

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎.github/workflows/build-and-publish-docs.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
- name: Checkout
1515
uses: actions/checkout@v4
1616

17-
- name: Generate pdoc documentation
17+
- name: Generate sphinx documentation
1818
uses: ./.github/actions/build-docs
1919
with:
2020
python-version: 3.11
@@ -24,7 +24,7 @@ jobs:
2424
env:
2525
SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
2626
with:
27-
source-directory: pdoc
27+
source-directory: docsbuild
2828
destination-github-username: pinecone-io
2929
destination-repository-name: sdk-docs
3030
user-email: clients@pinecone.io

‎.github/workflows/on-pr-dep-change.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ jobs:
3030
if: ${{ always() }}
3131
needs:
3232
- dependency-tests
33+
- create-project
3334
uses: './.github/workflows/project-cleanup.yaml'
3435
secrets: inherit
3536
with:

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,7 @@ venv.bak/
144144
pdoc/*
145145
!pdoc/pinecone-python-client-fork.png
146146
!pdoc/favicon-32x32.png
147+
docsbuild
147148

148149
# mypy
149150
.mypy_cache/

‎docs/_static/custom.css‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
body,
2+
div.body h1,
3+
div.body h2,
4+
div.body h3,
5+
div.body h4,
6+
div.body h5,
7+
div.body h6,
8+
div.admonition p.admonition-title {
9+
font-family: "Inter", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
10+
}
11+
12+
.blurb {
13+
font-size: 16px;
14+
}
15+
16+
p.admonition-title:after {
17+
content: "";
18+
}
19+
20+
div.code-block-caption {
21+
background-color: #EEE;
22+
border-bottom: 1px solid #CCC;
23+
font-size: 17px;
24+
padding: 10px;
25+
}
26+
27+
dt:target {
28+
background-color: #E8E8E8;
29+
}
30+
31+
.highlight {
32+
background-color: #F8F8F8;
33+
}

‎docs/_static/pinecone-logo.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/asyncio.rst‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
===============
2+
PineconeAsyncio
3+
===============
4+
5+
.. autoclass:: pinecone::PineconeAsyncio
6+
7+
.. automethod:: pinecone::PineconeAsyncio.__init__
8+
9+
DB Control Plane
10+
================
11+
12+
Indexes
13+
-------
14+
15+
.. automethod:: pinecone::PineconeAsyncio.create_index
16+
17+
.. automethod:: pinecone::PineconeAsyncio.create_index_for_model
18+
19+
.. automethod:: pinecone::PineconeAsyncio.create_index_from_backup
20+
21+
.. automethod:: pinecone::PineconeAsyncio.list_indexes
22+
23+
.. automethod:: pinecone::PineconeAsyncio.describe_index
24+
25+
.. automethod:: pinecone::PineconeAsyncio.configure_index
26+
27+
.. automethod:: pinecone::PineconeAsyncio.delete_index
28+
29+
.. automethod:: pinecone::PineconeAsyncio.has_index
30+
31+
Backups
32+
-------
33+
34+
.. automethod:: pinecone::PineconeAsyncio.create_backup
35+
36+
.. automethod:: pinecone::PineconeAsyncio.list_backups
37+
38+
.. automethod:: pinecone::PineconeAsyncio.describe_backup
39+
40+
.. automethod:: pinecone::PineconeAsyncio.delete_backup
41+
42+
Collections
43+
-----------
44+
45+
.. automethod:: pinecone::PineconeAsyncio.create_collection
46+
47+
.. automethod:: pinecone::PineconeAsyncio.list_collections
48+
49+
.. automethod:: pinecone::PineconeAsyncio.describe_collection
50+
51+
.. automethod:: pinecone::PineconeAsyncio.delete_collection
52+
53+
Restore Jobs
54+
------------
55+
56+
.. automethod:: pinecone::PineconeAsyncio.list_restore_jobs
57+
58+
.. automethod:: pinecone::PineconeAsyncio.describe_restore_job
59+
60+
DB Data Plane
61+
=============
62+
63+
.. autoclass:: pinecone.db_data::IndexAsyncio
64+
65+
.. automethod:: pinecone.db_data::IndexAsyncio.__init__
66+
67+
.. automethod:: pinecone.db_data::IndexAsyncio.describe_index_stats
68+
69+
Vectors
70+
-------
71+
72+
.. automethod:: pinecone.db_data::IndexAsyncio.upsert
73+
74+
.. automethod:: pinecone.db_data::IndexAsyncio.query
75+
76+
.. automethod:: pinecone.db_data::IndexAsyncio.query_namespaces
77+
78+
.. automethod:: pinecone.db_data::IndexAsyncio.delete
79+
80+
.. automethod:: pinecone.db_data::IndexAsyncio.fetch
81+
82+
.. automethod:: pinecone.db_data::IndexAsyncio.list
83+
84+
.. automethod:: pinecone.db_data::IndexAsyncio.list_paginated
85+
86+
Records
87+
-------
88+
89+
If you have created an index using integrated inference, you can use the following methods to
90+
search and retrieve records.
91+
92+
.. automethod:: pinecone.db_data::IndexAsyncio.search
93+
94+
.. automethod:: pinecone.db_data::IndexAsyncio.search_records
95+
96+
97+
98+
Inference
99+
=========
100+
101+
.. automethod:: pinecone.inference::Inference.embed
102+
103+
.. automethod:: pinecone.inference::Inference.rerank
104+
105+
.. automethod:: pinecone.inference::Inference.list_models
106+
107+
.. automethod:: pinecone.inference::Inference.get_model

‎docs/conf.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import pinecone
2+
3+
project = "Pinecone Python SDK"
4+
author = "Pinecone Systems, Inc."
5+
version = pinecone.__version__
6+
copyright = "%Y, Pinecone Systems, Inc."
7+
8+
html_baseurl = "https://sdk.pinecone.io/python"
9+
html_static_path = ["_static"]
10+
html_favicon = "favicon-32x32.png"
11+
12+
extensions = [
13+
"sphinx.ext.autodoc",
14+
"sphinx.ext.viewcode",
15+
"sphinx.ext.todo",
16+
"sphinx.ext.napoleon",
17+
"sphinx.ext.coverage",
18+
"sphinx.ext.autodoc.typehints",
19+
"myst_parser",
20+
]
21+
22+
# -- HTML Configuration -------------------------------------------------
23+
24+
html_theme = "alabaster"
25+
html_theme_options = {
26+
"logo": "pinecone-logo.svg",
27+
"description": "Pinecone Python SDK",
28+
"github_user": "pinecone-io",
29+
"github_repo": "pinecone-python-client",
30+
"github_button": True,
31+
"fixed_sidebar": True,
32+
"page_width": "1140px",
33+
"sidebar_width": "300px",
34+
"show_related": False,
35+
"show_powered_by": False,
36+
"extra_nav_links": {
37+
"Github Source": "https://github.com/pinecone-io/pinecone-python-client",
38+
"Pinecone Home": "https://pinecone.io",
39+
"Pinecone Docs": "https://docs.pinecone.io",
40+
"Pinecone Console": "https://app.pinecone.io",
41+
},
42+
}

‎docs/db_control/pod-indexes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,6 @@ pc.configure_index(
151151
)
152152
```
153153

154-
# Configuring, listing, describing, and deleting
154+
## Configuring, listing, describing, and deleting
155155

156156
See [shared index actions](shared-index-actions.md) to learn about how to manage the lifecycle of your index after it is created.

0 commit comments

Comments
 (0)