Implement docs with sphinx

Author: jhamon

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

@@ -17,11 +17,4 @@ runs:
     - name: Build html documentation
       shell: bash
       run: |
-        poetry run pdoc pinecone '!pinecone.core' '!pinecone.utils' --favicon ./favicon-32x32.png --docformat google -o ./pdoc
-
-    - name: Fix relative links
-      shell: bash
-      run: |
-        poetry run python3 ./.github/actions/build-docs/fix-relative-links.py ./pdoc ./pdoc
-      env:
-        BASE_URL: "https://github.com/pinecone-io/pinecone-python-client/blob/main/"
+        poetry run sphinx-build -b html sphinx docsbuild

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

@@ -24,7 +24,7 @@ jobs:
         env:
           SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
         with:
-          source-directory: pdoc
+          source-directory: docsbuild
           destination-github-username: pinecone-io
           destination-repository-name: sdk-docs
           user-email: [email protected]

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

@@ -144,6 +144,7 @@ venv.bak/
 pdoc/*
 !pdoc/pinecone-python-client-fork.png
 !pdoc/favicon-32x32.png
+docsbuild
 
 # mypy
 .mypy_cache/

.gitignore

@@ -71,8 +71,6 @@
         "pinecone.db_data.errors",
         "SparseValuesDictionaryExpectedError",
     ),
-    "Index": ("pinecone.db_data.import_error", "Index"),
-    "Inference": ("pinecone.db_data.import_error", "Inference"),
 }
 
 _db_control_lazy_imports = {

pinecone/__init__.py

@@ -1,7 +1,7 @@
 from pinecone.config import Config
 from pinecone.config import ConfigBuilder
 from pinecone.config import PineconeConfig
-from .exceptions import (
+from pinecone.exceptions import (
     PineconeException,
     PineconeApiTypeError,
     PineconeApiValueError,

pinecone/__init__.pyi

@@ -1,19 +1,14 @@
 from .index import (
-    Index as _Index,
+    Index,
     FetchResponse,
     QueryResponse,
     DescribeIndexStatsResponse,
     UpsertResponse,
     SparseValues,
     Vector,
 )
+
 from .dataclasses import *
-from .import_error import (
-    Index,
-    IndexClientInstantiationError,
-    Inference,
-    InferenceInstantiationError,
-)
 from .index_asyncio import *
 from .errors import (
     VectorDictionaryMissingKeysError,
@@ -24,19 +19,23 @@
     SparseValuesDictionaryExpectedError,
     MetadataDictionaryExpectedError,
 )
+import warnings
+
 
 from .resources.sync.bulk_import import ImportErrorMode
 
+_Index = Index  # alias for backwards compatibility
+
+
 __all__ = [
     "_Index",
     "_IndexAsyncio",
     "DescribeIndexStatsResponse",
     "FetchResponse",
     "ImportErrorMode",
     "Index",
-    "IndexClientInstantiationError",
+    "IndexAsyncio",
     "Inference",
-    "InferenceInstantiationError",
     "MetadataDictionaryExpectedError",
     "QueryResponse",
     "SearchQuery",
@@ -53,8 +52,6 @@
     "VectorTupleLengthError",
 ]
 
-import warnings
-
 
 def _get_deprecated_import(name, from_module, to_module):
     warnings.warn(
@@ -66,10 +63,10 @@ def _get_deprecated_import(name, from_module, to_module):
     )
     # Import from the new location
     from pinecone.inference import (
-        Inference as _Inference, # noqa: F401
-        AsyncioInference as _AsyncioInference, # noqa: F401
-        RerankModel, # noqa: F401
-        EmbedModel, # noqa: F401
+        Inference as _Inference,  # noqa: F401
+        AsyncioInference as _AsyncioInference,  # noqa: F401
+        RerankModel,  # noqa: F401
+        EmbedModel,  # noqa: F401
     )
 
     return locals()[name]

pinecone/db_data/__init__.py

@@ -524,16 +524,17 @@ def list_imports(self, **kwargs) -> Iterator["ImportModel"]:
             Returns a generator that yields each import operation. It automatically handles pagination tokens on your behalf so you can
             easily iterate over all results. The `list_imports` method accepts all of the same arguments as list_imports_paginated
 
-        ```python
-        for op in index.list_imports():
-            print(op)
-        ```
+        .. code-block:: python
+
+            for op in index.list_imports():
+                print(op)
+
 
         You can convert the generator into a list by wrapping the generator in a call to the built-in `list` function:
 
-        ```python
-        operations = list(index.list_imports())
-        ```
+        .. code-block:: python
+
+            operations = list(index.list_imports())
 
         You should be cautious with this approach because it will fetch all operations at once, which could be a large number
         of network calls and a lot of memory to hold the results.

pinecone/db_data/import_error.py

@@ -61,7 +61,7 @@
 logger = logging.getLogger(__name__)
 """ @private """
 
-__all__ = ["_IndexAsyncio"]
+__all__ = ["_IndexAsyncio", "IndexAsyncio"]
 
 _OPENAPI_ENDPOINT_PARAMS = (
     "_return_http_data_only",
@@ -649,3 +649,6 @@ async def cancel_import(self, id: str):
             id (str): The id of the import operation to cancel.
         """
         return await self.bulk_import.cancel(id=id)
+
+
+IndexAsyncio = _IndexAsyncio