The Standard Domain¶

Added in version 1.0.

The so-called “standard” domain collects all markup that doesn’t warrant a domain of its own. Its directives and roles are not prefixed with a domain name.

The standard domain is also where custom object descriptions, added using the add_object_type() API, are placed.

There is a set of directives allowing documenting command-line programs:

.. option:: name args, name args, ...¶

Describes a command line argument or switch. Option argument names should be enclosed in angle brackets. Examples:

.. option:: dest_dir

   Destination directory.

.. option:: -m <module>, --module <module>

   Run a module as a script.

The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you’d use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

Changed in version 5.3: One can cross-reference including an option value: :option:`--module=foobar`, ,``:option:–module[=foobar]`` or :option:`--module foobar`.

Use option_emphasise_placeholders for parsing of “variable part” of a literal text (similarly to the samp role).

cmdoption directive is a deprecated alias for the option directive.

.. confval:: name¶

Describes a configuration value or setting that the documented code or program uses or defines. Referenceable by confval.

:type: (text)¶: Describes the type of the configuration value. This is optional, and if specified will be interpreted as reStructuredText.

:default: (text)¶: Describes the default value of the configuration value. This is optional, and if specified will be interpreted as reStructuredText.

Example:

.. confval:: the_answer
   :type: ``int`` (a *number*)
   :default: **42**

   This is a setting that controls the value of the answer.

will be rendered as follows:

the_answer¶

Type:: int (a number)
Default:: 42

This is a setting that controls the value of the answer.

.. envvar:: name¶: Describes an environment variable that the documented code or program uses or defines. Referenceable by envvar.

.. program:: name¶

Like py:currentmodule, this directive produces no output. Instead, it serves to notify Sphinx that all following option directives document options for the program called name.

If you use program, you have to qualify the references in your option roles by the program name, so if you have the following situation

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r <revision>

   Specify the revision to work upon.

then :option:`rm -r` would refer to the first option, while :option:`svn -r` would refer to the second one.

If None is passed to the argument, the directive will reset the current program name.

The program name may contain spaces (in case you want to document subcommands like svn add and svn commit separately).

Added in version 0.5.

There is also a very generic object description directive, which is not tied to any domain:

.. describe:: text¶

.. object:: text¶

This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets. Example:

.. describe:: PAPER

   You can set this variable to select a paper size.