autodoc-traits

autodoc-traits is a Sphinx extension that builds on sphinx.ext.autodoc to better document classes with Traitlets based configuration. autodoc-traits provides the Sphinx directives autoconfigurable (use with classes) and autotrait (use with the traitlets based configuration options).

The sphinx.ext.autodoc provided directive [automodule][], which can overview classes, will with autodoc-traits enabled use autoconfigurable over autoclass for classes has trait based configuration. Similarly, the sphinx.ext.autodoc provided autoclass directive will use autotrait over autoattribute if configured to present the traitlets attributes normally not presented.

The autoattribute directive will provide a header looking like trait c.SampleConfigurable.trait = Bool(False), and as docstring it will use the trait's configured help text.

How to use it

1. Install autodoc-traits:

   pip install autodoc-traits
   

2. Configure Sphinx to use the autodoc_traits extensions in a Sphinx project's 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 will be registered by autodoc_traits,
       # but can safely be registered again.
       # ...
   ]
   

3. Make use of the sphinx.ext.autodoc Sphinx directive like automodule that document classes, the autodoc_traits provided autoconfigurable that documents traitlets configurable classes, or the autodoc_traits provided autotrait that documents individual traitlets configuration options:

   From a .rst document:

   .. automodule:: sample_module
      :members:
   
   .. autoconfigurable:: sample_module.SampleConfigurable
   
   .. autotrait:: sample_module.SampleConfigurable.trait
   

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}
.. autoconfigurable:: sample_module.SampleConfigurable
```

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.