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 |
|---|---|
Global option |
|
Entry with |
|
Entry with |
|
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.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:
- Returns:
A generator yielding the lines of the reStructuredText description.