Implement docs with sphinx

[jhamon]

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

• 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

[jhamon]

This file is the main entry point for sphinx when the static site is regenerated.

The .. toctree:: directive is how navigation is defined and dictates what other content is pulled in.

[jhamon]

To determine what methods are actually documented, they need to be declared in an rst file that is mentioned in the root toctree. Currently we have three things we're documenting: Pinecone in rest.rst, PineconeAsyncio in asyncio.rst, and PineconeGRPC in grpc.rst.

[jhamon]

We're using something called myst-parser to suck in some content that already existed in the repo as markdown files and render it into the sphinx static site. For the most part it does a good job, but the myst-parser didn't handle this comment block syntax. I think this is a github-specific addition to the markdown syntax, so I guess I'm not surprised.

[jhamon]

In the past we were doing some weird stuff where we aliased the real implementation of Index to _Index and then threw an error message if anybody tried to directly instantiate the Index class. I can't remember now, but I think this was something a field engineer requested.

I decided to nix these because it was causing a problem when generating docs. In the past, this was added to chastise people if they tried to instantiate the Index class without going through a parent client object such as Pinecone (which was handling a bunch of configuration stuff), but that small benefit is not worth having wonky looking documentation.

[jhamon]

Since I removed pdoc, this workflow got triggered and I noticed this mistake in my recent "create a project for every test run" PR.

[jhamon]

This is a minor atrocity, but for now it's the best way to work around sphinx's relatively narrow python version support. Poetry won't let me install it normally (and add it as a dev dependency in pyproject.toml) because our library has a wider range of python version support than sphinx.

[rohanshah18]

Nice work, LGTM!