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.

  1. Install the documentation dependencies in your virtual environment:

    python -m pip install 'momotor-engine-options[docs]'
    
  2. 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.autodoc itself.

  3. Add an autooptiondefvar directive 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 doc field.

  4. Link to the generated option with the momotor:option role:

    See :momotor:option:`label@checklet`.
    

    Use name@domain for a qualified option name. For the checklet domain, you can omit @checklet.

  5. 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.