autodoc-traits

autodoc-traits is a Sphinx extension that influences sphinx.ext.autodoc's provided Sphinx directives, specifically autoclass and autoattribute, to better document classes with Traitlets based configuration.

The autoclass directive is updated to document class attributes inheriting from traitlets.TraitType by default. The autoattribute directive is updated to provide a header looking like default_url c.KubeSpawner.default_url = Unicode('').

The extension also provides the autoconfigurable directive mapping to the autoclass directive, and the autotrait directive mapping to the autoattributes directive.

How to use it

1. Install autodoc-traits:

   pip install autodoc-traits
   

2. Configure Sphinx to use the autodoc_traits and sphinx.ext.autodoc extensions in a Sphinx projects conf.py file:

   # -- General Sphinx configuration --------------------------------------------
   # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
   #
   extensions = [
       "autodoc_traits",
       "sphinx.ext.autodoc",
       # ...
   ]
   

3. Make use of a sphinx.ext.autodoc Sphinx directive like autoclass, or automodule that make use of autoclass:

   From a .rst document:

   .. autoclass:: KubeSpawner
   

Use with MyST Parser

While you can use myst-parser, sphinx.ext.autodoc's directives emits unparsed rST, forcing us to parse the autodoc directives in a rST context.

From a .md document, with myst-parser:

```{eval-rst}
.. autoclass:: KubeSpawner
```

Due to this, also the Python docstrings are required to be in rST as well. Addressing this can be tracked from executablebooks/team-compass issue #6.