Sphinx option extension

momotor.options.sphinx.option registers the momotor domain and the autooptiondefvar documenter. Generate documentation for option definitions describes the setup.

Added in version 2.0.0: The momotor.options.sphinx.option extension, including the autooptiondefvar documenter and the momotor:option directive and role.

Generated entries

autooptiondefvar imports an OptionDefinition instance by its Python path. The documenter uses document_option_definition() to render its fields. An explicit directive selects the custom documenter even when automodule would describe the instance as generic Python data.

Manual entries and references

The momotor:option directive accepts an option name and an optional domain. Its content is reStructuredText. For example:

.. momotor:option:: timeout

   Maximum runtime in seconds.

   :type: integer
   :required: False
   :multiple: False
   :location: config, step, recipe
   :default: 30

The directive supports :checklet:, :step:, :canonical:, and :deprecated: options. A nonempty :deprecated: message adds a deprecation notice. :canonical: links to the defining checklet and needs a Sphinx extension that provides the momotor:checklet role.

Option references use these targets:

Entry

Target for momotor:option

Global option

timeout@checklet or timeout

Entry with :step: build

build:timeout

Entry with :checklet: example.Check

example.Check.Meta.options.timeout

A leading ~ shortens the displayed link text. A leading . searches the current Python class or Momotor step context before the global option name.

Added in version 2.1.0: Resolution of option references against the current Momotor step context.

Generator API

momotor.options.sphinx.option.document_option_definition(option, tab_width=8, style='checklet', *, checklet=None, canonical=None, step=None, no_index_entry=False, no_contents_entry=False, values=None, default=<object object>)

Generate a reStructuredText description for the given option definition.

Parameters:
  • option (OptionDefinition) – The option definition to document.

  • tab_width (int) – The tab width to use for indentation.

  • style (str) – The style to use for the option (‘checklet’ or ‘step’).

  • no_index_entry (bool) – Whether to suppress the index entry for this option.

  • no_contents_entry (bool) – Whether to suppress the contents entry for this option.

  • checklet (str | None) – The checklet name (full path including module) to use for the option.

  • canonical (str | None) – The canonical checklet (full path including module) that defines this option.

  • step (str | None) – The step name to use for the option.

  • values (list[Any] | None) – The values to use for the option. If provided, the option’s default value is ignored.

  • default (Any) – Alternate default value to use for the option. Overrides the option’s default value.

Return type:

Generator[str, None, None]

Returns:

A generator yielding the lines of the reStructuredText description.