Improvements for Python API documentation

I have recently implemented an extensive set of additional functionality/customizations to Sphinx for building the documentation for tensorstore:

https://google.github.io/tensorstore/python/api/index.html

I think that many of the changes that I made would also be useful to many other users, and would perhaps be good fits to incorporate into Sphinx itself, but I wanted to find out if there was interest in that.

Because a large amount of monkey patching was required, it would be easier to either add the functionality directly to Sphinx, or at least add necessary hooks such that monkey patching would not be required.

The theme itself is derived from mkdocs-material (see https://github.com/bashtage/sphinx-material/pull/96 for details on that), but some other improvements were inspired by pdoc3.

The specific changes include:

• Inclusion of object descriptions in the table of contents, along with optional "icons" (the icons are actually just single letters inside a box). The "icon" provides a concise indication of the object type. For example, "[C]" for Python class, "[F]" for Python function, "[$]" for environment variable, etc. (See: https://google.github.io/tensorstore/python/api/index.html)
  • Status: Table of contents now includes object descriptions. Icons not implemented.
• Support for "object synopses", a brief description text shown as a tooltip (i.e. HTML title attribute) when hovering over an object (in the Sphinx domain object sense) reference link. Currently there needs to be specific per-domain support for these, e.g. for Python objects it is set from the first paragraph of the doc comment. (Hover over links on the right table of contents here, for example: https://google.github.io/tensorstore/python/api/index.html) These are also added to the search index and shown in the search results.
  • Status: No change
• Support for pybind11 overloaded functions. Each overloaded function has its own signature and docstring, which are extracted from the combined docstring that pybind11 generates. Additionally, I specify a unique identifier for each overload, that can be used for cross-referencing and also for use in the object identifier and page name. See for example the multiple "Constructors" listed here: https://google.github.io/tensorstore/python/api/tensorstore.Context.html and corresponding source code here showing the syntax used for specifying the overload id: https://github.com/google/tensorstore/blob/b14939b1b8fa15a210dc3ba67e4bf9bd3cb3908a/python/tensorstore/context.cc#L414
  • Status: No change
• Support for doxygen-style "Group" names within doc comments, to group members: see for example https://github.com/google/tensorstore/blob/b14939b1b8fa15a210dc3ba67e4bf9bd3cb3908a/python/tensorstore/context.cc#L376
  • Status: No change
• New "autosummary" implementation. Rather than using a table to display the summary, the summary just contains another copy of the object description, but with the signature and description abbreviated, and slightly reduced padding. This provides a more consistent styling. (Also supports the "Group" names and multiple overloads.)
  • Status: No change
• A new "function parameter" object type for the Python domain, along with a :py:param role for referencing it. Function parameters are also added to the table of contents, and linked from the signature as well: https://google.github.io/tensorstore/python/api/tensorstore.open.html
  (Similar to https://github.com/sqlalchemyorg/sphinx-paramlinks)
  • Status: No change

Review the linked TensorStore API documentation and the listed Sphinx customizations first, then inspect Sphinx's Python-domain and autosummary entry points. The issue needs a maintainer-selected scope and agreed behavior for the chosen feature before completion can be judged.