sphinx/doc/usage/domains/restructuredtext.rst

.. highlight:: rst

===========================
The reStructuredText Domain
===========================

.. versionadded:: 1.0

The reStructuredText domain (name **rst**) provides the following directives:

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

   Describes a reStructuredText directive.
   The *name* can be a single directive name or actual directive syntax
   (`..` prefix and `::` suffix) with arguments that will be rendered differently.
   For example::

      .. rst:directive:: foo

         Foo description.

      .. rst:directive:: .. bar:: baz

         Bar description.

   will be rendered as:

   .. rst:directive:: foo
      :no-contents-entry:
      :no-index-entry:

      Foo description.

   .. rst:directive:: .. bar:: baz
      :no-contents-entry:
      :no-index-entry:

      Bar description.

.. rst:directive:: .. rst:directive:option:: name

   Describes an option for reStructuredText directive.  The *name* can be a single option
   name or option name with arguments which separated with colon (``:``).
   For example::

       .. rst:directive:: toctree

          .. rst:directive:option:: caption: caption of ToC

          .. rst:directive:option:: glob

   will be rendered as:

   .. rst:directive:: toctree
      :no-index:

      .. rst:directive:option:: caption: caption of ToC
         :no-index:

      .. rst:directive:option:: glob
         :no-index:

   .. rubric:: options

   .. rst:directive:option:: type: description of argument
      :type: text

      Describe the type of option value.

      For example::

         .. rst:directive:: toctree

            .. rst:directive:option:: maxdepth
               :type: integer or no value

      .. versionadded:: 2.1

.. rst:directive:: .. rst:role:: name

   Describes a reStructuredText role.  For example::

      .. rst:role:: foo

         Foo description.

   will be rendered as:

   .. rst:role:: foo
      :no-contents-entry:
      :no-index-entry:

      Foo description.

.. _rst-xref-roles:

These roles are provided to refer to the described objects:

.. rst:role:: rst:dir
              rst:role