Generate documentation for option definitions¶
Use the Sphinx extension to generate option reference entries from
OptionDefinition instances. The generated entry
contains the description, type, required flag, multiple-value settings,
locations, and default value.
Install the documentation dependencies in your virtual environment:
python -m pip install 'momotor-engine-options[docs]'
Add the extension to your Sphinx
conf.py:extensions = ['momotor.options.sphinx.option']
Keep your other extensions when you add this entry. The option extension loads
sphinx.ext.autodocitself.Add an
autooptiondefvardirective with the import path of a definition. For example, this directive documents the label copied to preflight results:.. autooptiondefvar:: momotor.options.domain.scheduler.preflight.LABEL_OPTION
For your own definition, replace the path with the module and variable name that Sphinx can import. Put its reStructuredText description in the definition’s
docfield.Link to the generated option with the
momotor:optionrole:See :momotor:option:`label@checklet`.
Use
name@domainfor a qualified option name. For thecheckletdomain, you can omit@checklet.Build the documentation from the directory containing
docs:python -m sphinx -E -n -W --keep-going -b html docs/source docs/build/html
Open
docs/build/html/index.html. Check that the generated option includes its description and that the option link opens that entry.
Use an explicit autooptiondefvar directive for each definition. Generic
automodule output can list a definition as Python data without generating an
option entry. Document each definition once to avoid duplicate option targets.
See Sphinx option extension for manual entries and links scoped to checklets or steps.