Reformat docstrings across Python client

[austin-denoble]

Problem

In a previous revision we added CI tooling for generating and deploying documentation for the Python client. #207

There was a lot of follow-up needed to clean up the generated documentation. A lot of our existing docstrings were also of disparate formatting types.

Solution

• Exclude the /pinecone/core/* modules and info.py module from the built output.
• Align our manually maintained docstrings around the Google format: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings.
• Add examples, fix up wording, flesh out descriptions, etc.

It was tricky aligning on a specific docstring format to go with. It seems like a lot of the auto-generated comments in /core/ are of either reST (reStructuredText, the sphinx default) or Google. A lot of the docstrings that were already stubbed out were of the Google style.

Since pdoc handles both types I went with Google as it felt a bit terser in terms of number of lines. Ultimately, I think most docs utilities offer plugins or options to handle either type.

Type of Change

• New feature (non-breaking change which adds functionality)
• Non-code change (docs, etc)

Test Plan

Easiest way to validate the output would probably be to pull this branch down locally and run the pdoc utility:

$ poetry shell
$ poetry install

# same command we use in the `build-docs` action
$ poetry run pdoc pinecone/ '!pinecone.core' '!pinecone.info' --favicon ./favicon-32x32.png --docformat google -o ./docs

Once built, you can open the index.html file within the /docs/ folder.

[austin-denoble]

Similar to our TS client, I added in an example configuration file.

[austin-denoble]

This was the only thing I changed in here and it seems like there was some auto-formatting applied.

[austin-denoble]

I don't think the previous default value worked for having the configuration file in the same location as the repo, but maybe the intent here was different? Tested and this works for me locally.

[austin-denoble]

Slipped a section in here for setting up an INI file. I don't think this was documented at all previously.