sphinx/doc/usage/domains/restructuredtext.rst

.. highlight:: rst

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

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

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

   Describes a reST 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-index:

      Foo description.

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

      Bar description.

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

   Describes an option for reST 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 reST role.  For example::

      .. rst:role:: foo

         Foo description.

   will be rendered as:

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

      Foo description.

.. _rst-roles:

These roles are provided to refer to the described objects:

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