sphinx/doc/usage/domains/standard.rst

.. highlight:: rst

===================
The Standard Domain
===================

.. versionadded:: 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
:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.

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

.. rst:directive:: .. 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 :rst:role:`option` (in the example case, you'd use something
   like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).

   .. versionchanged:: 5.3

      One can cross-reference including an option value: ``:option:`--module=foobar```,
      ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```.

   Use :confval:`option_emphasise_placeholders` for parsing of
   "variable part" of a literal text (similarly to the :rst:role:`samp` role).

   ``cmdoption`` directive is a deprecated alias for the ``option`` directive.

.. rst:directive:: .. confval:: name

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

   .. rst:directive:option:: type
      :type: text

      Describes the type of the configuration value.
      This is optional, and if specified will be interpreted as reStructuredText.

   .. rst:directive:option:: default
      :type: text

      Describes the default value of the configuration value.
      This is optional, and if specified will be interpreted as reStructuredText.

   Example:

   .. code-block:: rst

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

   .. confval:: the_answer
      :no-contents-entry:
      :no-index-entry:
      :type: ``int`` (a *number*)
      :default: **42**

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

.. rst:directive:: .. envvar:: name

   Describes an environment variable that the documented code or program uses
   or defines.  Referenceable by :rst:role:`envvar`.

.. rst:directive:: .. program:: name

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

   If you use :rst:dir:`program`, you have to qualify the references in your
   :rst:role:`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).

   .. versionadded:: 0.5

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

.. rst:directive:: .. 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.