Skip to main content

Sphinx extension to autodoc traitlets

Project description

autodoc-traits

Latest PyPI version GitHub Discourse Gitter

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

autodoc_traits-1.2.0.tar.gz (16.2 kB view hashes)

Uploaded Source

Built Distribution

autodoc_traits-1.2.0-py3-none-any.whl (7.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page