Consolidate sphinx and docs directories

jhamon · jhamon · commit 19705ea86a29 · 2025-06-03T15:32:06.000-04:00
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,14 @@
+body,
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6,
+div.admonition p.admonition-title {
+    font-family: "Inter", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
+}
+
+.blurb {
+    font-size: 16px;
+}
diff --git a/docs/_static/pinecone-logo.svg b/docs/_static/pinecone-logo.svg
@@ -0,0 +1 @@
+<svg enable-background="new 0 0 1077 220" viewBox="0 0 1077 220" xmlns="http://www.w3.org/2000/svg"><g fill="#111"><path d="m246.4 51.4h55.2c39.9 0 50.1 23.5 50.1 42.6s-10.3 42.6-50.1 42.6h-34.1v67.2h-21.1zm21.2 67.2h27.9c16.8 0 33.5-3.8 33.5-24.5s-16.8-24.5-33.5-24.5h-27.9z"/><path d="m379.4 50.7c8 0 14.5 6.3 14.6 14 .1 7.8-6.2 14.2-14.2 14.4s-14.6-5.9-14.9-13.7c-.1-3.9 1.4-7.6 4.1-10.4 2.6-2.7 6.4-4.3 10.4-4.3zm-9.8 51.1h19.6v102.1h-19.6z"/><path d="m412 101.8h19.9v15.8h.5c6.9-12 20.3-19.2 34.4-18.3 20.3 0 37.8 11.9 37.8 39v65.7h-19.6v-60.2c0-19.2-11.3-26.3-23.9-26.3-16.5 0-29.1 10.3-29.1 34v52.5h-20z"/><path d="m540.9 160c0 17.8 17 29.5 35.3 29.5 11.5-.3 22.2-6 28.7-15.2l15.1 11.2c-11 14.1-28.4 22-46.5 21.1-33.2 0-53.8-23.2-53.8-53.6-.6-14.2 4.9-28 15.1-38.1s24.2-15.7 38.8-15.5c36.9 0 51 27.5 51 53.8v6.9h-83.7zm62.8-15.5c-.5-17-10.2-29.5-30.2-29.5-17.1-.1-31.4 12.8-32.5 29.5z"/><path d="m714.6 129c-6.5-7.5-16-11.7-26.1-11.4-21.6 0-32.7 17-32.7 36.2-.5 9.1 2.8 17.9 9.2 24.5s15.3 10.3 24.6 10.2c9.8.3 19.2-3.9 25.4-11.4l14.1 13.6c-10.3 10.6-24.8 16.3-39.7 15.7-14.7.7-29-4.6-39.4-14.8-10.4-10.1-16-24.1-15.3-38.4-.7-14.4 4.9-28.4 15.3-38.6s24.7-15.7 39.5-15.2c15.1-.4 29.7 5.5 40.2 16.1z"/><path d="m787.9 99.2c30.2.5 54.4 24.7 54.1 54.2s-25 53.2-55.3 53c-30.2-.2-54.7-24.1-54.7-53.6 0-14.4 5.9-28.1 16.4-38.2 10.6-10.1 24.8-15.6 39.5-15.4zm0 89.2c21.1 0 34.4-14.7 34.4-35.6 0-20.8-13.3-35.5-34.4-35.5s-34.5 14.7-34.5 35.5 13.3 35.6 34.5 35.6z"/><path d="m859.7 101.8h19.9v15.8c6.9-12.1 20.4-19.2 34.5-18.3 20.3 0 37.8 11.9 37.8 39v65.7h-19.9v-60.2c0-19.2-11.3-26.3-23.8-26.3-16.6 0-29.1 10.3-29.1 34v52.5h-19.3v-102.2z"/><path d="m988.8 160c0 17.8 17 29.5 35.3 29.5 11.5-.4 22.2-6 28.7-15.2l15.1 11.2c-11 14-28.3 21.8-46.4 20.8-33.1 0-53.8-23.2-53.8-53.6-.6-14.2 4.9-28.1 15.1-38.2 10.2-10.2 24.3-15.7 38.9-15.4 36.9 0 51 27.5 51 53.8v6.9zm62.7-15.6c-.5-17-10.1-29.5-30.2-29.5-17.1-.1-31.4 12.8-32.5 29.5z"/><path clip-rule="evenodd" d="m127 6.4c-2.1-2.5-5.6-3.1-8.4-1.5l-2.6 1.4-28.3 16.1 6.6 11.6 18.4-10.5-4.5 24.6 13.1 2.4 4.6-24.7 13.6 16.2 10.2-8.6-20.6-24.6h-.1zm-39.7 207.5c6.8 0 12.3-5.4 12.3-12s-5.5-12-12.3-12-12.3 5.4-12.3 12c-.1 6.6 5.5 12 12.3 12zm16.5-65.9-4.4 24.7-13.2-2.4 4.4-24.6-18.4 10.6-6.7-11.6 28.1-16.1 2.6-1.5c2.8-1.6 6.3-1 8.4 1.5l2 2.4 20.9 24.5-10.2 8.7zm10.7-59-4.4 24.7-13.2-2.4 4.4-24.5-18.3 10.5-6.6-11.6 28-16v-.2h.2l2.6-1.5c2.8-1.6 6.3-1 8.4 1.5l2 2.3 20.8 24.6-10.2 8.7zm-86.3 97.6h-.1l-2.7-.8c-2.9-.8-4.8-3.6-4.6-6.6l2.4-33.4 12.7.9-1.5 20.3 19.7-13.4 7.1 10.5-19.3 13.1 19.7 5.7-3.5 12.2zm130.7 13.8-.9 2.9c-.9 2.8-3.5 4.7-6.5 4.5l-2.8-.2-.2.1-.1-.1-31-2.1.8-12.7 20.6 1.4-13.5-18.9 10.3-7.4 13.8 19.4 6-19.6 12.1 3.7zm36.4-68.8 1.5 2.7c1.5 2.7.9 6.1-1.5 8.1l-2.2 1.9v.1h-.1l-24.1 20.4-8.4-9.9 15.8-13.4-23.7-4.2 2.3-12.8 23.9 4.2-10-18 11.3-6.3zm-24.5-55.8-21.4 11.5-6.2-11.4 21.1-11.3-19.3-7.9 4.9-12 29.4 11.9.1-.1.1.2 2.7 1.1c2.9 1.2 4.5 4.2 4 7.2l-.5 3-5.5 30.5-12.8-2.3zm-143.6 26.8 23.8 4-2.2 12.8-24-4.1 10.2 18-11.3 6.4-15.4-27.1-1.5-2.6c-1.5-2.7-.9-6.1 1.4-8.1l2.2-1.9v-.1h.1l23.8-20.5 8.5 9.9zm35.9-55.4 15.8 17.6-9.7 8.7-16.2-18-3.7 20.5-12.8-2.3 5.6-30.4.6-3.1c.5-3 3.1-5.2 6.1-5.3l2.8-.1.1-.1.1.1 31.8-1.3.5 13z" fill-rule="evenodd"/></g></svg>
diff --git a/docs/asyncio.rst b/docs/asyncio.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,8 +3,11 @@
 project = "Pinecone Python SDK"
 author = "Pinecone Systems, Inc."
 version = pinecone.__version__
+copyright = "%Y, Pinecone Systems, Inc."
 
 html_baseurl = "https://sdk.pinecone.io/python"
+html_static_path = ["_static"]
+html_favicon = "favicon-32x32.png"
 
 extensions = [
     "sphinx.ext.autodoc",
@@ -13,19 +16,27 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.coverage",
     "sphinx.ext.autodoc.typehints",
+    "myst_parser",
 ]
 
 # -- HTML Configuration -------------------------------------------------
 
 html_theme = "alabaster"
 html_theme_options = {
+    "logo": "pinecone-logo.svg",
+    "description": "Pinecone Python SDK",
     "github_user": "pinecone-io",
     "github_repo": "pinecone-python-client",
     "github_button": True,
     "fixed_sidebar": True,
     "page_width": "1140px",
-    "show_related": True,
-    # 'analytics_id': '', # TODO: add analytics id
-    "description": version,
+    "sidebar_width": "300px",
+    "show_related": False,
     "show_powered_by": False,
+    "extra_nav_links": {
+        "Github Source": "https://github.com/pinecone-io/pinecone-python-client",
+        "Pinecone Home": "https://pinecone.io",
+        "Pinecone Docs": "https://docs.pinecone.io",
+        "Pinecone Console": "https://app.pinecone.io",
+    },
 }
diff --git a/docs/db_control/pod-indexes.md b/docs/db_control/pod-indexes.md
@@ -151,6 +151,6 @@ pc.configure_index(
 )
 ```
 
-# Configuring, listing, describing, and deleting
+## Configuring, listing, describing, and deleting
 
 See [shared index actions](shared-index-actions.md) to learn about how to manage the lifecycle of your index after it is created.
diff --git a/docs/db_control/serverless-indexes.md b/docs/db_control/serverless-indexes.md
@@ -126,6 +126,6 @@ pc.create_index(
 )
 ```
 
-# Configuring, listing, describing, and deleting
+## Configuring, listing, describing, and deleting
 
 See [shared index actions](shared-index-actions.md) to learn about how to manage the lifecycle of your index after it is created.
diff --git a/docs/db_control/shared-index-configs.md b/docs/db_control/shared-index-configs.md
@@ -1,4 +1,4 @@
-# Optional Index configurations
+# Index configuration
 
 This page covers some optional configurations that can be used with all index types.
 
diff --git a/docs/db_data/index-usage-byov.md b/docs/db_data/index-usage-byov.md
@@ -1,4 +1,4 @@
-# Using your Pinecone index
+# Vectors
 
 ## Describe index statistics
 
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,3 +1,5 @@
+# FAQ
+
 ## How does connection pooling work in the Pinecone SDK?
 
 Before any data can be sent or received from Pinecone, your application must first establish a TCP connection with our API gateway. Establishing a TCP connection is a costly operation from a performance standpoint and so we use connection pooling to cache and reuse these connections across many different requests.
diff --git a/docs/favicon-32x32.png b/docs/favicon-32x32.png
diff --git a/docs/grpc.rst b/docs/grpc.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,11 +1,24 @@
 .. toctree::
    :maxdepth: 5
    :hidden:
+   :caption: Reference
 
    rest
    asyncio
    grpc
 
+.. toctree::
+   :maxdepth: 5
+   :hidden:
+   :caption: Usage Info
+
+   upgrading
+   FAQ <faq>
+   working-with-indexes
+   db_data/index-usage-byov.md
+   db_control/collections.md
+   inference/inference-api.md
+
 ===================
 Pinecone Python SDK
 ===================
diff --git a/docs/inference/inference-api.md b/docs/inference/inference-api.md
diff --git a/docs/rest.rst b/docs/rest.rst
diff --git a/docs/upgrading.md b/docs/upgrading.md
@@ -1,9 +1,10 @@
-> [!NOTE]
-> The official SDK package was renamed from `pinecone-client` to `pinecone` beginning in version 5.1.0.
-> Please remove `pinecone-client` from your project dependencies and add `pinecone` instead to get
-> the latest updates.
+# Upgrading
 
-# Upgrading from `6.x` to `7.x`
+The official SDK package was renamed from `pinecone-client` to `pinecone` beginning in version 5.1.0.
+Please remove `pinecone-client` from your project dependencies and add `pinecone` instead to get
+the latest updates.
+
+## Upgrading from `6.x` to `7.x`
 
 There are no intentional breaking changes when moving from v6 to v7 of the SDK. The major version bump reflects the move from calling the `2025-01` to the `2025-04` version of the underlying API.
 
@@ -196,16 +197,16 @@ pc.create_index(
 )
 ```
 
-# Upgrading from `5.x` to `6.x`
+## Upgrading from `5.x` to `6.x`
 
-## Breaking changes in 6.x
+### Breaking changes in 6.x
 - Dropped support for Python 3.8, which has now reached [official end of life](https://devguide.python.org/versions/). We added support for Python 3.13.
 - Removed the explicit dependency on [`tqdm`](https://github.com/tqdm/tqdm) which is used to provide a nice progress bar when upserting lots of data into Pinecone. If `tqdm` is available in the environment the Pinecone SDK will detect and use it but we will no longer require `tqdm` to be installed in order to run the SDK. Popular notebook platforms such as [Jupyter](https://jupyter.org/) and [Google Colab](https://colab.google/) already include `tqdm` in the environment by default so for many users this will not require any changes, but if you are running small scripts in other environments and want to continue seeing the progress bars you will need to separately install the `tqdm` package.
 - Removed some previously deprecated and rarely used keyword arguments (`config`, `openapi_config`, and `index_api`) to instead prefer dedicated keyword arguments for individual settings such as `api_key`, `proxy_url`, etc. These keyword arguments were primarily aimed at facilitating testing but were never documented for the end-user so we expect few people to be impacted by the change. Having multiple ways of passing in the same configuration values was adding significant amounts of complexity to argument validation, testing, and documentation that wasn't really being repaid by significant ease of use, so we've removed those options.
 
 ## Useful additions in 6.x:
 
-## Compatibility with `asyncio`
+### Compatibility with `asyncio`
 
 The v6 Python SDK introduces a new client variants, `PineconeAsyncio` and `IndexAsyncio`, which provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). This should unblock those who wish to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), [Sanic](https://sanic.dev/), etc.
 
@@ -349,7 +350,7 @@ sparse_index.query(
 )
 ```
 
-## Configuration UX with enums
+### Configuration UX with enums
 
 Many enum objects have been added to help with the discoverability of some configuration options. Type hints in your editor will now suggest enums such as `Metric`, `AwsRegion`, `GcpRegion`, `PodType`, `EmbedModel`, `RerankModel` and more to help you quickly get going without having to go looking for documentation examples. This is a backwards compatible change and you should still be able to pass string values for fields exactly as before if you have preexisting code.
 
@@ -396,17 +397,17 @@ pc.create_index(
 Both ways of working are equally valid. Some may prefer the more concise nature of passing simple string values, but others may prefer the support your editor gives you to tab complete when working with enums.
 
 
-# Upgrading from `4.x` to `5.x`
+## Upgrading from `4.x` to `5.x`
 
 As part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (`openapi_config`) was removed in favor of individual configuration options such as `proxy_url`, `proxy_headers`, and `ssl_ca_certs`. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.
 
 It is no longer necessary to install a separate plugin, `pinecone-plugin-inference`, to try out the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference); that plugin is now installed by default in the v5 SDK. See [usage instructions below](#inference-api).
 
 
-# Upgrading from `3.x` to `4.x`
+## Upgrading from `3.x` to `4.x`
 
 For this upgrade you are unlikely to be impacted by breaking changes unless you are using the `grpc` extras to use `PineconeGRPC` and have other dependencies in your project which place constraints on your grpc version. The `pinecone[grpc]` extras package got a breaking change to the underlying `grpcio` dependency to unlock significant performance improvements. Read full details in these [v4 Release Notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0).
 
-# Upgrading to `3.x`:
+## Upgrading to `3.x`
 
 Many things were changed in the v3 SDK to pave the way for Pinecone's new Serverless index offering as well as put in place a more object-oriented foundation for developing the SDK. These changes are covered in detail in the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3). Serverless indexes are only available in `3.x` release versions or greater.
diff --git a/docs/working-with-indexes.rst b/docs/working-with-indexes.rst
@@ -0,0 +1,10 @@
+Indexes
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   db_control/serverless-indexes
+   db_control/pod-indexes
+   db_control/shared-index-actions
+   db_control/shared-index-configs
diff --git a/pinecone/db_data/index_asyncio_interface.py b/pinecone/db_data/index_asyncio_interface.py
@@ -242,7 +242,7 @@ async def main():
 
             asyncio.run(main())
 
-          Returns: An empty dictionary if the delete operation was successful.
+        Returns: An empty dictionary if the delete operation was successful.
         """
         pass
 
diff --git a/pinecone/db_data/interfaces.py b/pinecone/db_data/interfaces.py
@@ -426,7 +426,7 @@ def delete(
             >>> index.delete(filter={'key': 'value'}, namespace='my_namespace')
 
 
-          Returns: An empty dictionary if the delete operation was successful.
+        Returns: An empty dictionary if the delete operation was successful.
         """
         pass
 
diff --git a/pinecone/grpc/pinecone.py b/pinecone/grpc/pinecone.py
@@ -17,10 +17,10 @@ class PineconeGRPC(Pinecone):
     .. code-block:: bash
 
         # Install the latest version
-        pip3 install pinecone[grpc]
+        pip3 install "pinecone[grpc]"
 
         # Install a specific version
-        pip3 install "pinecone[grpc]"
+        pip3 install "pinecone[grpc]"==7.0.2
 
     **Installing with poetry**
 
@@ -30,7 +30,7 @@ class PineconeGRPC(Pinecone):
         poetry add pinecone --extras grpc
 
         # Install a specific version
-        poetry add pinecone --extras grpc
+        poetry add pinecone==7.0.2 --extras grpc
 
 
     **Using the gRPC client**
diff --git a/pinecone/legacy_pinecone_interface.py b/pinecone/legacy_pinecone_interface.py
@@ -257,10 +257,11 @@ def create_index_for_model(
                 )
 
 
-        See also:
+        .. seealso::
 
-        * See `available cloud regions <https://docs.pinecone.io/troubleshooting/available-cloud-regions>`_
-        * See the `Model Gallery <https://docs.pinecone.io/models/overview>`_ to learn about available models
+            Official docs on `available cloud regions <https://docs.pinecone.io/troubleshooting/available-cloud-regions>`_
+
+            `Model Gallery <https://docs.pinecone.io/models/overview>`_ to learn about available models
 
         """
         pass

Original file line number	Diff line number	Diff line change
`@@ -151,6 +151,6 @@ pc.configure_index(`
`151`	`151`	`)`
`152`	`152`	```
`153`	`153`
`154`		`-# Configuring, listing, describing, and deleting`
	`154`	`+## Configuring, listing, describing, and deleting`
`155`	`155`
`156`	`156`	`See [shared index actions](shared-index-actions.md) to learn about how to manage the lifecycle of your index after it is created.`
Original file line number	Diff line number	Diff line change
`@@ -126,6 +126,6 @@ pc.create_index(`
`126`	`126`	`)`
`127`	`127`	```
`128`	`128`
`129`		`-# Configuring, listing, describing, and deleting`
	`129`	`+## Configuring, listing, describing, and deleting`
`130`	`130`
`131`	`131`	`See [shared index actions](shared-index-actions.md) to learn about how to manage the lifecycle of your index after it is created.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Optional Index configurations`
	`1`	`+# Index configuration`
`2`	`2`
`3`	`3`	`This page covers some optional configurations that can be used with all index types.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Using your Pinecone index`
	`1`	`+# Vectors`
`2`	`2`
`3`	`3`	`## Describe index statistics`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# FAQ`
	`2`	`+`
`1`	`3`	`## How does connection pooling work in the Pinecone SDK?`
`2`	`4`
`3`	`5`	`Before any data can be sent or received from Pinecone, your application must first establish a TCP connection with our API gateway. Establishing a TCP connection is a costly operation from a performance standpoint and so we use connection pooling to cache and reuse these connections across many different requests.`