Autodoc_trait extension

Autodoc_trait extension#

Neba provides a Sphinx extension to automatically document your configuration. Add the extension to your sphinx configuration (in conf.py):

extensions = [
    ...,
    "neba.autodoc_trait",
]

This adds a new autodoc directive for sections (and applications):

.. autosection:: my_module.MySection

It will list traits from all subsections. It will not document any other attribute or methods.

Note

This uses the legacy autodoc implementation but it does not require you to activate it in your configuration.

Options#

Other autodoc options apply, but not all may work.

:inherited-members: (comma separated list)#

Works the same as for autodoc. If present, document traits the section inherits from parent classes. If a comma separated list, do not document traits inherited from those classes.

:member-order: (alphabetical, bysource or traits-first)#

  • alphabetical: Sort every trait and section in alphabetical order.

  • bysource: Keep the order from the source files.

  • traits-first: Keep the order from the source files, but put the traits of a section before its subsections.

:only-configurables:#

Only document configurable traits.

A good default is

.. autosection:: my_module.MySection
    :inherited-members: Configurable
    :member-order: bysource
    :only-configurables:

Example#

If we use it to document Application:

class Application(**kwargs)

Bases: Section

Base application class.

Orchestrate the loading of configuration keys from files or from command line arguments. Pass the combined configuration keys to the appropriate sections in the configuration tree structure. This validate the values and instantiate the configuration objects.

Parameters:

  • start (bool)

  • kwargs (Any)

config_files: Unicode | List[Unicode]

  • Default value: ['config.toml']

Path to configuration files. Either relative from interpreter working directory or absolute.

log_level: Enum | Int

  • Default value: "INFO"

  • Accepted values: "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"

  • Observers:

    • at _observe_log_format_change

Set the log level by value or name.

log_datefmt: Unicode

  • Default value: "%Y-%m-%d %H:%M:%S"

  • Observers:

    • at _observe_log_format_change

The date format used by logging formatters for ‘asctime’

log_format: Unicode

  • Default value: "[%(levelname)s]%(name)s:: %(message)s"

  • Observers:

    • at _observe_log_format_change

The Logging format template

On this page