Sphinx Domains

Sphinx includes a system for documenting objects in a structured way via domains. For example to document a Python function one might do:

.. py:function:: answer()

   :return: int The ultimate answer to life, the universe and everything.

   Return 42.

This is what the sphinx.ext.autodoc system does (e.g. autofunction) for you automatically.

For documenting Rose components an extension adding a Rose domain has been added.

Rose Domain

The Rose domain is for documenting Rose configurations and built-in applications.

Rose Objects:

The Rose domain supports the following object types:

rose:app - Rose Applications.
rose:file - Root Rose configurations.
rose:conf - Rose configurations. Nest them to create configuration sections.

See the corresponding directives for more information on each object type.

Reference Syntax:

Once documented, objects can be referenced using the following syntax:

:rose:CONFIG-FILE[parent-section]child-config
:rose:CONFIG-FILE|top-level-config

Where CONFIG-FILE is:

The APP-NAME for applications (e.g. fcm_make).
The FILE-NAME for configuration files (e.g. rose.conf).

Referencing From RST Files:

To reference a Rose object add the object TYPE into the domain (e.g. conf or app).

:rose:TYPE:`CONFIG-FILE[parent-section]child-config`

e.g:

* :rose:app:`fcm_make`
* :rose:conf:`fcm_make.args`

Autodocumentation:

Documentation can be auto-built from RST formatted comments in Rose configuration files using the autoconfig directive.

Note that due to the implementation of metomi.rose.config the autodocumenter will represent empty sections as top level configuration nodes.

Example

.. rose:file:: rose-suite.conf

   The config file used for configuring suite level settings.

   .. rose:conf:: jinja2:suite.rc

      A section for specifying Jinja2 settings for use in the
      ``flow.cylc`` file.

      Note that one ommits the square brackets for config sections. If
      :rose:conf: contains other :rose:conf:'s then it is implicitly a
      section and the brackets are added automatically. If you wish to
      document a section which contains no settings write it using
      square brackets.

      .. rose:conf:: ROSE_VERSION

         provide the intended Rose version to the suite.

         .. deprecated:: 6.1.0

            No longer required, this context is now provided internally.

      .. rose:conf:: CYLC_VERSION

         provide the intended Rose version to the suite.

         .. deprecated:: 6.1.0

            See :rose:conf:`ROSE_VERSION`.

            ..            ^ relative reference

Referencing Objects Via Intersphinx:

Reference Rose objects as you would any other e.g:

:rose:file:`intersphinx-mapping:rose-app.conf`

A quick way to get the object reference is to extract if from the URL. For example in the following URL:

doc-root/api/configuration/application.html#rose:file:rose-app.conf

The reference is rose:file:rose-app.conf.

class rose_domain.RoseDirective(*args, **kwargs)[source]

Base class for implementing Rose objects.

Subclasses must provide:

NAME

Subclasses can provide:

LABEL
ARGUMENT_SEPARATOR & ARGUMENT_REGEX
ALT_FORM_SEPARATOR
ALT_FORM_TEMPLATE
doc_field_types - List of Field objects for object parameters.
run() - For adding special rev_context variables via add_rev_context.
handle_signature() - For changing the display of objects.
custom_name_template - String template accepting one string format argument for custom formatting the node name (e.g. '[%s]' for conf sections).

ref_context Variables:

Sphinx domains use ref_context variables to determine the relationship between objects. E.g. for a Rose app the rose:app variable is set to the name of the app. This variable will be made available to all children which is how they determine that they belong to the app.

Variables set in run() are available to this object along with all of its children.
Variables set in before_content() are only available to children.
All variables set via add_ref_context() will be automatically removed in after_content() to prevent leaking scope.

ALT_FORM_SEPARATOR = '&': String for splitting alternate names.

ALT_FORM_TEMPLATE = '(alternate: %s)': String template for writing out alternate names. Takes one string format argument.

ARGUMENT_SEPARATOR = None: String for separating the configuration name and argument.

LABEL = '': Label to prepend to objects.

NAME = None: The Rose domain this directive implements, see RoseDomain.directives

class rose_domain.RoseAppDirective(*args, **kwargs)[source]

Directive for documenting Rose apps.

Example

Click source to view source code.

.. rose:app:: foo

   An app called ``foo``.

class rose_domain.RoseFileDirective(*args, **kwargs)[source]

Directive for documenting Rose files.

Example

Click source to view source code.

.. rose:file:: foo

   An configuration file called ``foo``.

class rose_domain.RoseConfigDirective(*args, **kwargs)[source]

Directive for documenting config sections.

Optional Attributes:

envvar - Associate an environment variable with this configuration option.
compulsory - Set to True for compulsory settings, omit this field for optional settings.

Additional ref_context:

rose:conf-section - Set for parent configurations, is available to any child nodes.

Example

Click source to view source code.

.. rose:conf:: foo

   :default: foo
   :opt argtype foo: Description of option ``foo``.
   :opt bar: Description of bar

   A setting called ``foo``.

.. rose:conf:: bar

   A section called ``bar``.

   .. rose:conf:: baz

      :compulsory: True
      :env: AN_ASSOCIATED_ENVIRONMENT_VARIABLE

      A config called ``[bar]baz``.

class rose_domain.RoseAutoDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Directive for autodocumenting Rose configuration files.

Uses RST formatted comments in Rose configuration files using metomi.rose.config.

Note the directive only documents config objects not the file itself.

Example

.. rose:file: foo.conf

   .. autoconfig:: path/to/foo.conf