Adding upstream version 7.2.6.upstream/7.2.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1311 insertions, 0 deletions

diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
new file mode 100644
index 0000000..1fd5b66
--- /dev/null
+++ b/doc/usage/restructuredtext/directives.rst
@@ -0,0 +1,1311 @@
+.. highlight:: rst
+
+==========
+Directives
+==========
+
+:ref:`As previously discussed <rst-directives>`, a directive is a generic block
+of explicit markup. While Docutils provides a number of directives, Sphinx
+provides many more and uses directives as one of the primary extension
+mechanisms.
+
+See :doc:`/usage/restructuredtext/domains` for roles added by domains.
+
+.. seealso::
+
+   Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview
+   of the directives provided by Docutils.
+
+
+.. _toctree-directive:
+
+Table of contents
+-----------------
+
+.. index:: pair: table of; contents
+
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents.  The ``toctree`` directive is the central element.
+
+.. note::
+
+   Simple "inclusion" of one file in another can be done with the
+   :dudir:`include` directive.
+
+.. note::
+
+   To create table of contents for current document (.rst file), use the
+   standard reST :dudir:`contents directive <table-of-contents>`.
+
+.. rst:directive:: toctree
+
+   This directive inserts a "TOC tree" at the current location, using the
+   individual TOCs (including "sub-TOC trees") of the documents given in the
+   directive body.  Relative document names (not beginning with a slash) are
+   relative to the document the directive occurs in, absolute names are relative
+   to the source directory.  A numeric ``maxdepth`` option may be given to
+   indicate the depth of the tree; by default, all levels are included. [#]_
+
+   The representation of "TOC tree" is changed in each output format.  The
+   builders that output multiple files (ex. HTML) treat it as a collection of
+   hyperlinks.  On the other hand, the builders that output a single file (ex.
+   LaTeX, man page, etc.) replace it with the content of the documents on the
+   TOC tree.
+
+   Consider this example (taken from the Python docs' library reference index)::
+
+      .. toctree::
+         :maxdepth: 2
+
+         intro
+         strings
+         datatypes
+         numeric
+         (many more documents listed here)
+
+   This accomplishes two things:
+
+   * Tables of contents from all those documents are inserted, with a maximum
+     depth of two, that means one nested heading.  ``toctree`` directives in
+     those documents are also taken into account.
+   * Sphinx knows the relative order of the documents ``intro``,
+     ``strings`` and so forth, and it knows that they are children of the shown
+     document, the library index.  From this information it generates "next
+     chapter", "previous chapter" and "parent chapter" links.
+
+   **Entries**
+
+   Document titles in the :rst:dir:`toctree` will be automatically read from the
+   title of the referenced document. If that isn't what you want, you can
+   specify an explicit title and target using a similar syntax to reST
+   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
+   looks like::
+
+       .. toctree::
+
+          intro
+          All about strings <strings>
+          datatypes
+
+   The second line above will link to the ``strings`` document, but will use the
+   title "All about strings" instead of the title of the ``strings`` document.
+
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
+   **Section numbering**
+
+   If you want to have section numbers even in HTML output, give the
+   **toplevel** toctree a ``numbered`` option.  For example::
+
+      .. toctree::
+         :numbered:
+
+         foo
+         bar
+
+   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
+   automatically numbered (don't give the ``numbered`` flag to those).
+
+   Numbering up to a specific depth is also possible, by giving the depth as a
+   numeric argument to ``numbered``.
+
+   **Additional options**
+
+   You can use the ``caption`` option to provide a toctree caption and you can
+   use the ``name`` option to provide an implicit target name that can be
+   referenced by using :rst:role:`ref`::
+
+      .. toctree::
+         :caption: Table of Contents
+         :name: mastertoc
+
+         foo
+
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
+   You can use "globbing" in toctree directives, by giving the ``glob`` flag
+   option.  All entries are then matched against the list of available
+   documents, and matches are inserted into the list alphabetically.  Example::
+
+      .. toctree::
+         :glob:
+
+         intro*
+         recipe/*
+         *
+
+   This includes first all documents whose names start with ``intro``, then all
+   documents in the ``recipe`` folder, then all remaining documents (except the
+   one containing the directive, of course.) [#]_
+
+   The special entry name ``self`` stands for the document containing the
+   toctree directive.  This is useful if you want to generate a "sitemap" from
+   the toctree.
+
+   You can use the ``reversed`` flag option to reverse the order of the entries
+   in the list. This can be useful when using the ``glob`` flag option to
+   reverse the ordering of the files.  Example::
+
+      .. toctree::
+         :glob:
+         :reversed:
+
+         recipe/*
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style, or in the HTML
+   sidebar.
+
+   In cases where you want to have only one top-level toctree and hide all other
+   lower level toctrees you can add the "includehidden" option to the top-level
+   toctree entry::
+
+      .. toctree::
+         :includehidden:
+
+         doc_1
+         doc_2
+
+   All other toctree entries can then be eliminated by the "hidden" option.
+
+   In the end, all documents in the :term:`source directory` (or subdirectories)
+   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
+   finds a file that is not included, because that means that this file will not
+   be reachable through standard navigation.
+
+   Use :confval:`exclude_patterns` to explicitly exclude documents or
+   directories from building completely.  Use :ref:`the "orphan" metadata
+   <metadata>` to let a document be built, but notify Sphinx that it is not
+   reachable via a toctree.
+
+   The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC
+   tree hierarchy.  It can be used as the documentation's main page, or as a
+   "full table of contents" if you don't give a ``maxdepth`` option.
+
+   .. versionchanged:: 0.3
+      Added "globbing" option.
+
+   .. versionchanged:: 0.6
+      Added "numbered" and "hidden" options as well as external links and
+      support for "self" references.
+
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
+   .. versionchanged:: 1.1
+      Added numeric argument to "numbered".
+
+   .. versionchanged:: 1.2
+      Added "includehidden" option.
+
+   .. versionchanged:: 1.3
+      Added "caption" and "name" option.
+
+Special names
+^^^^^^^^^^^^^
+
+Sphinx reserves some document names for its own use; you should not try to
+create documents with these names -- it will cause problems.
+
+The special document names (and pages generated for them) are:
+
+* ``genindex``, ``modindex``, ``search``
+
+  These are used for the general index, the Python module index, and the search
+  page, respectively.
+
+  The general index is populated with entries from modules, all
+  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
+  :rst:dir:`index` directives.
+
+  The Python module index contains one entry per :rst:dir:`py:module`
+  directive.
+
+  The search page contains a form that uses the generated JSON search index and
+  JavaScript to full-text search the generated documents for search words; it
+  should work on every major browser that supports modern JavaScript.
+
+* every name beginning with ``_``
+
+  Though few such names are currently used by Sphinx, you should not
+  create documents or document-containing directories with such names.  (Using
+  ``_`` as a prefix for a custom template directory is fine.)
+
+.. warning::
+
+   Be careful with unusual characters in filenames.  Some formats may interpret
+   these characters in unexpected ways:
+
+   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
+     may not work.
+
+   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
+     found.
+
+
+Paragraph-level markup
+----------------------
+
+.. index:: note, warning
+           pair: changes; in version
+
+These directives create short paragraphs and can be used inside information
+units as well as normal text.
+
+.. rst:directive:: .. note::
+
+   An especially important bit of information about an API that a user should be
+   aware of when using whatever bit of API the note pertains to.  The content of
+   the directive should be written in complete sentences and include all
+   appropriate punctuation.
+
+   Example::
+
+      .. note::
+
+         This function is not suitable for sending spam e-mails.
+
+.. rst:directive:: .. warning::
+
+   An important bit of information about an API that a user should be very aware
+   of when using whatever bit of API the warning pertains to.  The content of
+   the directive should be written in complete sentences and include all
+   appropriate punctuation. This differs from :rst:dir:`note` in that it is
+   recommended over :rst:dir:`note` for information regarding security.
+
+.. rst:directive:: .. versionadded:: version
+
+   This directive documents the version of the project which added the described
+   feature to the library or C API. When this applies to an entire module, it
+   should be placed at the top of the module section before any prose.
+
+   The first argument must be given and is the version in question; you can add
+   a second argument consisting of a *brief* explanation of the change.
+
+   Example::
+
+      .. versionadded:: 2.5
+         The *spam* parameter.
+
+   Note that there must be no blank line between the directive head and the
+   explanation; this is to make these blocks visually continuous in the markup.
+
+.. rst:directive:: .. versionchanged:: version
+
+   Similar to :rst:dir:`versionadded`, but describes when and what changed in
+   the named feature in some way (new parameters, changed side effects, etc.).
+
+.. rst:directive:: .. deprecated:: version
+
+   Similar to :rst:dir:`versionchanged`, but describes when the feature was
+   deprecated.  An explanation can also be given, for example to inform the
+   reader what should be used instead.  Example::
+
+      .. deprecated:: 3.1
+         Use :func:`spam` instead.
+
+.. rst:directive:: seealso
+
+   Many sections include a list of references to module documentation or
+   external documents.  These lists are created using the :rst:dir:`seealso`
+   directive.
+
+   The :rst:dir:`seealso` directive is typically placed in a section just before
+   any subsections.  For the HTML output, it is shown boxed off from the main
+   flow of the text.
+
+   The content of the :rst:dir:`seealso` directive should be a reST definition
+   list. Example::
+
+      .. seealso::
+
+         Module :py:mod:`zipfile`
+            Documentation of the :py:mod:`zipfile` standard module.
+
+         `GNU tar manual, Basic Tar Format <http://link>`_
+            Documentation for tar archive files, including GNU tar extensions.
+
+   There's also a "short form" allowed that looks like this::
+
+      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
+
+   .. versionadded:: 0.5
+      The short form.
+
+.. rst:directive:: .. rubric:: title
+
+   This directive creates a paragraph heading that is not used to create a
+   table of contents node.
+
+   .. note::
+
+      If the *title* of the rubric is "Footnotes" (or the selected language's
+      equivalent), this rubric is ignored by the LaTeX writer, since it is
+      assumed to only contain footnote definitions and therefore would create an
+      empty heading.
+
+.. rst:directive:: centered
+
+   This directive creates a centered boldfaced line of text.  Use it as
+   follows::
+
+      .. centered:: LICENSE AGREEMENT
+
+   .. deprecated:: 1.1
+      This presentation-only directive is a legacy from older versions.
+      Use a :ref:`rst-class <rstclass>` directive instead and add an
+      appropriate style.
+
+.. rst:directive:: hlist
+
+   This directive must contain a bullet list.  It will transform it into a more
+   compact list by either distributing more than one item horizontally, or
+   reducing spacing between items, depending on the builder.
+
+   For builders that support the horizontal distribution, there is a ``columns``
+   option that specifies the number of columns; it defaults to 2.  Example::
+
+      .. hlist::
+         :columns: 3
+
+         * A list of
+         * short items
+         * that should be
+         * displayed
+         * horizontally
+
+   .. versionadded:: 0.6
+
+
+.. _code-examples:
+
+Showing code examples
+---------------------
+
+.. index:: pair: code; examples
+           single: sourcecode
+
+There are multiple ways to show syntax-highlighted literal code blocks in
+Sphinx:
+
+* using :ref:`reST doctest blocks <rst-doctest-blocks>`;
+* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in
+  combination with the :rst:dir:`highlight` directive;
+* using the :rst:dir:`code-block` directive;
+* and using the :rst:dir:`literalinclude` directive.
+
+Doctest blocks can only be used
+to show interactive Python sessions, while the remaining three can be used for
+other languages. Of these three, literal blocks are useful when an entire
+document, or at least large sections of it, use code blocks with the same
+syntax and which should be styled in the same manner. On the other hand, the
+:rst:dir:`code-block` directive makes more sense when you want more fine-tuned
+control over the styling of each block or when you have a document containing
+code blocks using multiple varied syntaxes. Finally, the
+:rst:dir:`literalinclude` directive is useful for including entire code files
+in your documentation.
+
+In all cases, Syntax highlighting is provided by `Pygments
+<https://pygments.org>`_. When using literal blocks, this is configured using
+any :rst:dir:`highlight` directives in the source file. When a ``highlight``
+directive is encountered, it is used until the next ``highlight`` directive is
+encountered. If there is no ``highlight`` directive in the file, the global
+highlighting language is used. This defaults to ``python`` but can be
+configured using the :confval:`highlight_language` config value. The following
+values are supported:
+
+* ``none`` (no highlighting)
+* ``default`` (similar to ``python3`` but with a fallback to ``none`` without
+  warning highlighting fails; the default when :confval:`highlight_language`
+  isn't set)
+* ``guess`` (let Pygments guess the lexer based on contents, only works with
+  certain well-recognizable languages)
+* ``python``
+* ``rest``
+* ``c``
+* ... and any other `lexer alias that Pygments supports`__
+
+If highlighting with the selected language fails (i.e. Pygments emits an
+"Error" token), the block is not highlighted in any way.
+
+.. important::
+
+   The list of lexer aliases supported is tied to the Pygment version. If you
+   want to ensure consistent highlighting, you should fix your version of
+   Pygments.
+
+__ https://pygments.org/docs/lexers
+
+.. rst:directive:: .. highlight:: language
+
+   Example::
+
+      .. highlight:: c
+
+   This language is used until the next ``highlight`` directive is encountered.
+   As discussed previously, *language* can be any lexer alias supported by
+   Pygments.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: linenothreshold: threshold
+      :type: number (optional)
+
+      Enable to generate line numbers for code blocks.
+
+      This option takes an optional number as threshold parameter.  If any
+      threshold given, the directive will produce line numbers only for the code
+      blocks longer than N lines.  If not given, line numbers will be produced
+      for all of code blocks.
+
+      Example::
+
+         .. highlight:: python
+            :linenothreshold: 5
+
+   .. rst:directive:option:: force
+      :type: no value
+
+      If given, minor errors on highlighting are ignored.
+
+      .. versionadded:: 2.1
+
+.. rst:directive:: .. code-block:: [language]
+                   .. sourcecode:: [language]
+
+   Example::
+
+      .. code-block:: ruby
+
+         Some Ruby code.
+
+   The directive's alias name :rst:dir:`sourcecode` works as well.  This
+   directive takes a language name as an argument.  It can be `any lexer alias
+   supported by Pygments <https://pygments.org/docs/lexers/>`_.  If it is not
+   given, the setting of :rst:dir:`highlight` directive will be used.  If not
+   set, :confval:`highlight_language` will be used.  To display a code example
+   *inline* within other text, rather than as a separate block, you can use the
+   :rst:role:`code` role instead.
+
+   .. versionchanged:: 2.0
+      The ``language`` argument becomes optional.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: linenos
+      :type: no value
+
+      Enable to generate line numbers for the code block::
+
+         .. code-block:: ruby
+            :linenos:
+
+            Some more Ruby code.
+
+   .. rst:directive:option:: lineno-start: number
+      :type: number
+
+      Set the first line number of the code block.  If present, ``linenos``
+      option is also automatically activated::
+
+         .. code-block:: ruby
+            :lineno-start: 10
+
+            Some more Ruby code, with line numbering starting at 10.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: emphasize-lines: line numbers
+      :type: comma separated numbers
+
+      Emphasize particular lines of the code block::
+
+       .. code-block:: python
+          :emphasize-lines: 3,5
+
+          def some_function():
+              interesting = False
+              print 'This line is highlighted.'
+              print 'This one is not...'
+              print '...but this one is.'
+
+      .. versionadded:: 1.1
+      .. versionchanged:: 1.6.6
+         LaTeX supports the ``emphasize-lines`` option.
+
+   .. rst:directive:option: force
+      :type: no value
+
+      Ignore minor errors on highlighting
+
+      .. versionchanged:: 2.1
+
+   .. rst:directive:option:: caption: caption of code block
+      :type: text
+
+      Set a caption to the code block.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: name: a label for hyperlink
+      :type: text
+
+      Define implicit target name that can be referenced by using
+      :rst:role:`ref`.  For example::
+
+        .. code-block:: python
+           :caption: this.py
+           :name: this-py
+
+           print 'Explicit is better than implicit.'
+
+      In order to cross-reference a code-block using either the
+      :rst:role:`ref` or the :rst:role:`numref` role, it is necessary
+      that both :strong:`name` and :strong:`caption` be defined. The
+      argument of :strong:`name` can then be given to :rst:role:`numref`
+      to generate the cross-reference. Example::
+
+        See :numref:`this-py` for an example.
+
+      When using :rst:role:`ref`, it is possible to generate a cross-reference
+      with only :strong:`name` defined, provided an explicit title is
+      given. Example::
+
+        See :ref:`this code snippet <this-py>` for an example.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separated by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 1.4
+
+   .. rst:directive:option:: dedent: number
+      :type: number or no value
+
+      Strip indentation characters from the code block.  When number given,
+      leading N characters are removed.  When no argument given, leading spaces
+      are removed via :func:`textwrap.dedent()`.  For example::
+
+         .. code-block:: ruby
+            :linenos:
+            :dedent: 4
+
+                some ruby code
+
+      .. versionadded:: 1.3
+      .. versionchanged:: 3.5
+         Support automatic dedent.
+
+   .. rst:directive:option:: force
+      :type: no value
+
+      If given, minor errors on highlighting are ignored.
+
+      .. versionadded:: 2.1
+
+.. rst:directive:: .. literalinclude:: filename
+
+   Longer displays of verbatim text may be included by storing the example text
+   in an external file containing only plain text.  The file may be included
+   using the ``literalinclude`` directive. [#]_ For example, to include the
+   Python source file :file:`example.py`, use::
+
+      .. literalinclude:: example.py
+
+   The file name is usually relative to the current file's path.  However, if
+   it is absolute (starting with ``/``), it is relative to the top source
+   directory.
+
+   **Additional options**
+
+   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
+   option to switch on line numbers, the ``lineno-start`` option to select the
+   first line number, the ``emphasize-lines`` option to emphasize particular
+   lines, the ``name`` option to provide an implicit target name, the
+   ``dedent`` option to strip indentation characters for the code block, and a
+   ``language`` option to select a language different from the current file's
+   standard language. In addition, it supports the ``caption`` option; however,
+   this can be provided with no argument to use the filename as the caption.
+   Example with options::
+
+      .. literalinclude:: example.rb
+         :language: ruby
+         :emphasize-lines: 12,15-18
+         :linenos:
+
+   Tabs in the input are expanded if you give a ``tab-width`` option with the
+   desired tab width.
+
+   Include files are assumed to be encoded in the :confval:`source_encoding`.
+   If the file has a different encoding, you can specify it with the
+   ``encoding`` option::
+
+      .. literalinclude:: example.py
+         :encoding: latin-1
+
+   The directive also supports including only parts of the file.  If it is a
+   Python module, you can select a class, function or method to include using
+   the ``pyobject`` option::
+
+      .. literalinclude:: example.py
+         :pyobject: Timer.start
+
+   This would only include the code lines belonging to the ``start()`` method
+   in the ``Timer`` class within the file.
+
+   Alternately, you can specify exactly which lines to include by giving a
+   ``lines`` option::
+
+      .. literalinclude:: example.py
+         :lines: 1,3,5-10,20-
+
+   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
+
+   Another way to control which part of the file is included is to use the
+   ``start-after`` and ``end-before`` options (or only one of them).  If
+   ``start-after`` is given as a string option, only lines that follow the
+   first line containing that string are included.  If ``end-before`` is given
+   as a string option, only lines that precede the first lines containing that
+   string are included. The ``start-at`` and ``end-at`` options behave in a
+   similar way, but the lines containing the matched string are included.
+
+   ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string.
+   ``start-after``/``start-at`` filter lines before the line that contains
+   option string (``start-at`` will keep the line). Then ``end-before``/``end-at``
+   filter lines after the line that contains option string (``end-at`` will keep
+   the line and ``end-before`` skip the first line).
+
+   .. note::
+
+      If you want to select only ``[second-section]`` of ini file like the
+      following, you can use ``:start-at: [second-section]`` and
+      ``:end-before: [third-section]``:
+
+      .. code-block:: ini
+
+         [first-section]
+
+         var_in_first=true
+
+         [second-section]
+
+         var_in_second=true
+
+         [third-section]
+
+         var_in_third=true
+
+      Useful cases of these option is working with tag comments.
+      ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options
+      keep lines between comments:
+
+      .. code-block:: py
+
+         if __name__ == "__main__":
+             # [initialize]
+             app.start(":8000")
+             # [initialized]
+
+
+   When lines have been selected in any of the ways described above, the line
+   numbers in ``emphasize-lines`` refer to those selected lines, counted
+   consecutively starting at ``1``.
+
+   When specifying particular parts of a file to display, it can be useful to
+   display the original line numbers. This can be done using the
+   ``lineno-match`` option, which is however allowed only when the selection
+   consists of contiguous lines.
+
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
+   If you want to show the diff of the code, you can specify the old file by
+   giving a ``diff`` option::
+
+      .. literalinclude:: example.py
+         :diff: example.py.orig
+
+   This shows the diff between ``example.py`` and ``example.py.orig`` with
+   unified diff format.
+
+   A ``force`` option can ignore minor errors on highlighting.
+
+   .. versionchanged:: 0.4.3
+      Added the ``encoding`` option.
+
+   .. versionchanged:: 0.6
+      Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before``
+      options, as well as support for absolute filenames.
+
+   .. versionchanged:: 1.0
+      Added the ``prepend``, ``append``, and ``tab-width`` options.
+
+   .. versionchanged:: 1.3
+      Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and
+      ``dedent`` options.
+
+   .. versionchanged:: 1.4
+      Added the ``class`` option.
+
+   .. versionchanged:: 1.5
+      Added the ``start-at``, and ``end-at`` options.
+
+   .. versionchanged:: 1.6
+      With both ``start-after`` and ``lines`` in use, the first line as per
+      ``start-after`` is considered to be with line number ``1`` for ``lines``.
+
+   .. versionchanged:: 2.1
+      Added the ``force`` option.
+
+   .. versionchanged:: 3.5
+      Support automatic dedent.
+
+.. _glossary-directive:
+
+Glossary
+--------
+
+.. rst:directive:: .. glossary::
+
+   This directive must contain a reST definition-list-like markup with terms and
+   definitions.  The definitions will then be referenceable with the
+   :rst:role:`term` role.  Example::
+
+      .. glossary::
+
+         environment
+            A structure where information about all documents under the root is
+            saved, and used for cross-referencing.  The environment is pickled
+            after the parsing stage, so that successive runs only need to read
+            and parse new and changed documents.
+
+         source directory
+            The directory which, including its subdirectories, contains all
+            source files for one Sphinx project.
+
+   In contrast to regular definition lists, *multiple* terms per entry are
+   allowed, and inline markup is allowed in terms.  You can link to all of the
+   terms.  For example::
+
+      .. glossary::
+
+         term 1
+         term 2
+            Definition of both terms.
+
+   (When the glossary is sorted, the first term determines the sort order.)
+
+   If you want to specify "grouping key" for general index entries, you can put
+   a "key" as "term : key". For example::
+
+      .. glossary::
+
+         term 1 : A
+         term 2 : B
+            Definition of both terms.
+
+   Note that "key" is used for grouping key as is.
+   The "key" isn't normalized; key "A" and "a" become different groups.
+   The whole characters in "key" is used instead of a first character; it is
+   used for "Combining Character Sequence" and "Surrogate Pairs" grouping key.
+
+   In i18n situation, you can specify "localized term : key" even if original
+   text only have "term" part. In this case, translated "localized term" will be
+   categorized in "key" group.
+
+   .. versionadded:: 0.6
+      You can now give the glossary directive a ``:sorted:`` flag that will
+      automatically sort the entries alphabetically.
+
+   .. versionchanged:: 1.1
+      Now supports multiple terms and inline markup in terms.
+
+   .. versionchanged:: 1.4
+      Index key for glossary term should be considered *experimental*.
+
+   .. versionchanged:: 4.4
+      In internationalized documentation, the ``:sorted:`` flag sorts
+      according to translated terms.
+
+Meta-information markup
+-----------------------
+
+.. rst:directive:: .. sectionauthor:: name <email>
+
+   Identifies the author of the current section.  The argument should include
+   the author's name such that it can be used for presentation and email
+   address.  The domain name portion of the address should be lower case.
+   Example::
+
+      .. sectionauthor:: Guido van Rossum <guido@python.org>
+
+   By default, this markup isn't reflected in the output in any way (it helps
+   keep track of contributions), but you can set the configuration value
+   :confval:`show_authors` to ``True`` to make them produce a paragraph in the
+   output.
+
+
+.. rst:directive:: .. codeauthor:: name <email>
+
+   The :rst:dir:`codeauthor` directive, which can appear multiple times, names
+   the authors of the described code, just like :rst:dir:`sectionauthor` names
+   the author(s) of a piece of documentation.  It too only produces output if
+   the :confval:`show_authors` configuration value is ``True``.
+
+
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all object descriptions (like
+functions, classes or attributes) like discussed in
+:doc:`/usage/restructuredtext/domains`.
+
+However, there is also explicit markup available, to make the index more
+comprehensive and enable index entries in documents where information is not
+mainly contained in information units, such as the language reference.
+
+.. rst:directive:: .. index:: <entries>
+
+   This directive contains one or more index entries.  Each entry consists of a
+   type and a value, separated by a colon.
+
+   For example::
+
+      .. index::
+         single: execution; context
+         pair: module; __main__
+         pair: module; sys
+         triple: module; search; path
+         seealso: scope
+
+      The execution context
+      ---------------------
+
+      ...
+
+   This directive contains five entries, which will be converted to entries in
+   the generated index which link to the exact location of the index statement
+   (or, in case of offline media, the corresponding page number).
+
+   Since index directives generate cross-reference targets at their location in
+   the source, it makes sense to put them *before* the thing they refer to --
+   e.g. a heading, as in the example above.
+
+   The possible entry types are:
+
+   single
+      Creates a single index entry.
+      Can be made a sub-entry by separating the sub-entry text with a semicolon
+      (this notation is also used below to describe what entries are created).
+      Examples:
+
+      .. code:: reStructuredText
+
+         .. index:: single: execution
+                    single: execution; context
+
+      - ``single: execution`` creates an index entry labelled ``execution``.
+      - ``single: execution; context`` creates an sub-entry of ``execution``
+        labelled ``context``.
+   pair
+      A shortcut to create two index entries.
+      The pair of values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: pair: loop; statement
+
+      This would create two index entries; ``loop; statement`` and ``statement; loop``.
+   triple
+      A shortcut to create three index entries.
+      All three values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: triple: module; search; path
+
+      This would create three index entries; ``module; search path``,
+      ``search; path, module``, and ``path; module search``.
+   see
+      A shortcut to create an index entry that refers to another entry.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: see: entry; other
+
+      This would create an index entry referring from ``entry`` to ``other``
+      (i.e. 'entry': See 'other').
+   seealso
+      Like ``see``, but inserts 'see also' instead of 'see'.
+   module, keyword, operator, object, exception, statement, builtin
+      These **deprecated** shortcuts all create two index entries.
+      For example, ``module: hashlib`` creates the entries ``module; hashlib``
+      and ``hashlib; module``.
+
+      .. deprecated:: 1.0
+         These Python-specific entry types are deprecated.
+
+      .. versionchanged:: 7.1
+         Removal version set to Sphinx 9.0.
+         Using these entry types will now emit warnings with the ``index`` category.
+
+   You can mark up "main" index entries by prefixing them with an exclamation
+   mark.  The references to "main" entries are emphasized in the generated
+   index.  For example, if two pages contain ::
+
+      .. index:: Python
+
+   and one page contains ::
+
+      .. index:: ! Python
+
+   then the backlink to the latter page is emphasized among the three backlinks.
+
+   For index directives containing only "single" entries, there is a shorthand
+   notation::
+
+      .. index:: BNF, grammar, syntax, notation
+
+   This creates four index entries.
+
+   .. versionchanged:: 1.1
+      Added ``see`` and ``seealso`` types, as well as marking main entries.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: name: a label for hyperlink
+      :type: text
+
+      Define implicit target name that can be referenced by using
+      :rst:role:`ref`.  For example::
+
+        .. index:: Python
+           :name: py-index
+
+   .. versionadded:: 3.0
+
+.. rst:role:: index
+
+   While the :rst:dir:`index` directive is a block-level markup and links to the
+   beginning of the next paragraph, there is also a corresponding role that sets
+   the link target directly where it is used.
+
+   The content of the role can be a simple phrase, which is then kept in the
+   text and used as an index entry.  It can also be a combination of text and
+   index entry, styled like with explicit targets of cross-references.  In that
+   case, the "target" part can be a full entry as described for the directive
+   above.  For example::
+
+      This is a normal reST :index:`paragraph` that contains several
+      :index:`index entries <pair: index; entry>`.
+
+   .. versionadded:: 1.1
+
+
+.. _tags:
+
+Including content based on tags
+-------------------------------
+
+.. rst:directive:: .. only:: <expression>
+
+   Include the content of the directive only if the *expression* is true.  The
+   expression should consist of tags, like this::
+
+      .. only:: html and draft
+
+   Undefined tags are false, defined tags (via the ``-t`` command-line option or
+   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
+   expressions, also using parentheses (like ``html and (latex or draft)``) are
+   supported.
+
+   The *format* and the *name* of the current builder (``html``, ``latex`` or
+   ``text``) are always set as a tag [#]_.  To make the distinction between
+   format and name explicit, they are also added with the prefix ``format_`` and
+   ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
+   ``format_html`` and ``builder_epub``.
+
+   These standard tags are set *after* the configuration file is read, so they
+   are not available there.
+
+   All tags must follow the standard Python identifier syntax as set out in
+   the `Identifiers and keywords
+   <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_
+   documentation.  That is, a tag expression may only consist of tags that
+   conform to the syntax of Python variables.  In ASCII, this consists of the
+   uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``
+   and, except for the first character, the digits ``0`` through ``9``.
+
+   .. versionadded:: 0.6
+   .. versionchanged:: 1.2
+      Added the name of the builder and the prefixes.
+
+   .. warning::
+
+      This directive is designed to control only content of document.  It could
+      not control sections, labels and so on.
+
+.. _table-directives:
+
+Tables
+------
+
+Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
+
+- grid table syntax (:duref:`ref <grid-tables>`),
+- simple table syntax (:duref:`ref <simple-tables>`),
+- :dudir:`csv-table` syntax,
+- or :dudir:`list-table` syntax.
+
+The :dudir:`table` directive serves as optional wrapper of the *grid* and
+*simple* syntaxes.
+
+They work fine in HTML output, but rendering tables to LaTeX is complex.
+Check the :confval:`latex_table_style`.
+
+.. versionchanged:: 1.6
+   Merged cells (multi-row, multi-column, both) from grid tables containing
+   complex contents such as multiple paragraphs, blockquotes, lists, literal
+   blocks, will render correctly to LaTeX output.
+
+.. rst:directive:: .. tabularcolumns:: column spec
+
+   This directive influences only the LaTeX output for the next table in
+   source.  The mandatory argument is a column specification (known as an
+   "alignment preamble" in LaTeX idiom).  Please refer to a LaTeX
+   documentation, such as the `wiki page`_, for basics of such a column
+   specification.
+
+   .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables
+
+   .. versionadded:: 0.3
+
+   .. note::
+
+      :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table
+      directives.  If both are specified, ``:widths:`` option will be ignored.
+
+   Sphinx will render tables with more than 30 rows with ``longtable``.
+   Besides the ``l``, ``r``, ``c`` and ``p{width}`` column specifiers, one can
+   also use ``\X{a}{b}`` (new in version 1.5) which configures the column
+   width to be a fraction ``a/b`` of the total line width and ``\Y{f}`` (new
+   in version 1.6) where ``f`` is a decimal: for example ``\Y{0.2}`` means that
+   the column will occupy ``0.2`` times the line width.
+
+   When this directive is used for a table with at most 30 rows, Sphinx will
+   render it with ``tabulary``.  One can then use specific column types ``L``
+   (left), ``R`` (right), ``C`` (centered) and ``J`` (justified).  They have
+   the effect of a ``p{width}`` (i.e. each cell is a LaTeX ``\parbox``) with
+   the specified internal text alignment and an automatically computed
+   ``width``.
+
+   .. warning::
+
+      - Cells that contain list-like elements such as object descriptions,
+        blockquotes or any kind of lists are not compatible with the ``LRCJ``
+        column types.  The column type must then be some ``p{width}`` with an
+        explicit ``width`` (or ``\X{a}{b}`` or ``\Y{f}``).
+
+      - Literal blocks do not work with ``tabulary`` at all.  Sphinx will
+        fall back to ``tabular`` or ``longtable`` environments and generate a
+        suitable column specification.
+
+In absence of the :rst:dir:`tabularcolumns` directive, and for a table with at
+most 30 rows and no problematic cells as described in the above warning,
+Sphinx uses ``tabulary`` and the ``J`` column-type for every column.
+
+.. versionchanged:: 1.6
+
+   Formerly, the ``L`` column-type was used (text is flushed-left).  To revert
+   to this, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact
+   Sphinx uses ``T`` and sets it by default to be an alias of ``J``.
+
+.. hint::
+
+   A frequent issue with ``tabulary`` is that columns with little contents
+   appear to be "squeezed".  One can add to the LaTeX preamble for example
+   ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``,
+   the ``tabulary`` default of ``10pt`` being too small.
+
+.. hint::
+
+   To force usage of the LaTeX ``longtable`` environment pass ``longtable`` as
+   a ``:class:`` option to :dudir:`table`, :dudir:`csv-table`, or
+   :dudir:`list-table`.  Use :ref:`rst-class <rstclass>` for other tables.
+
+Math
+----
+
+The input language for mathematics is LaTeX markup.  This is the de-facto
+standard for plain-text math notation and has the added advantage that no
+further translation is necessary when building LaTeX output.
+
+Keep in mind that when you put math markup in **Python docstrings** read by
+:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
+or use Python raw strings (``r"raw"``).
+
+.. rst:directive:: math
+
+   Directive for displayed math (math that takes the whole line for itself).
+
+   The directive supports multiple equations, which should be separated by a
+   blank line::
+
+      .. math::
+
+         (a + b)^2 = a^2 + 2ab + b^2
+
+         (a - b)^2 = a^2 - 2ab + b^2
+
+   In addition, each single equation is set within a ``split`` environment,
+   which means that you can have multiple aligned lines in an equation,
+   aligned at ``&`` and separated by ``\\``::
+
+      .. math::
+
+         (a + b)^2  &=  (a + b)(a + b) \\
+                    &=  a^2 + 2ab + b^2
+
+   For more details, look into the documentation of the `AmSMath LaTeX
+   package`_.
+
+   When the math is only one line of text, it can also be given as a directive
+   argument::
+
+      .. math:: (a + b)^2 = a^2 + 2ab + b^2
+
+   Normally, equations are not numbered.  If you want your equation to get a
+   number, use the ``label`` option.  When given, it selects an internal label
+   for the equation, by which it can be cross-referenced, and causes an equation
+   number to be issued.  See :rst:role:`eq` for an example.  The numbering
+   style depends on the output format.
+
+   There is also an option ``nowrap`` that prevents any wrapping of the given
+   math in a math environment.  When you give this option, you must make sure
+   yourself that the math is properly set up.  For example::
+
+      .. math::
+         :nowrap:
+
+         \begin{eqnarray}
+            y    & = & ax^2 + bx + c \\
+            f(x) & = & x^2 + 2xy + y^2
+         \end{eqnarray}
+
+.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
+
+.. seealso::
+
+   :ref:`math-support`
+      Rendering options for math with HTML builders.
+
+   :confval:`latex_engine`
+      Explains how to configure LaTeX builder to support Unicode literals in
+      math mark-up.
+
+
+Grammar production displays
+---------------------------
+
+Special markup is available for displaying the productions of a formal grammar.
+The markup is simple and does not attempt to model all aspects of BNF (or any
+derived forms), but provides enough to allow context-free grammars to be
+displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
+the definition of the symbol.  There is this directive:
+
+.. rst:directive:: .. productionlist:: [productionGroup]
+
+   This directive is used to enclose a group of productions.  Each production
+   is given on a single line and consists of a name, separated by a colon from
+   the following definition.  If the definition spans multiple lines, each
+   continuation line must begin with a colon placed at the same column as in
+   the first line.
+   Blank lines are not allowed within ``productionlist`` directive arguments.
+
+   The definition can contain token names which are marked as interpreted text
+   (e.g., "``sum ::= `integer` "+" `integer```") -- this generates
+   cross-references to the productions of these tokens.  Outside of the
+   production list, you can reference to token productions using
+   :rst:role:`token`.
+
+   The *productionGroup* argument to :rst:dir:`productionlist` serves to
+   distinguish different sets of production lists that belong to different
+   grammars.  Multiple production lists with the same *productionGroup* thus
+   define rules in the same scope.
+
+   Inside of the production list, tokens implicitly refer to productions
+   from the current group. You can refer to the production of another
+   grammar by prefixing the token with its group name and a colon, e.g,
+   "``otherGroup:sum``". If the group of the token should not be shown in
+   the production, it can be prefixed by a tilde, e.g.,
+   "``~otherGroup:sum``". To refer to a production from an unnamed
+   grammar, the token should be prefixed by a colon, e.g., "``:sum``".
+
+   Outside of the production list,
+   if you have given a *productionGroup* argument you must prefix the
+   token name in the cross-reference with the group name and a colon,
+   e.g., "``myGroup:sum``" instead of just "``sum``".
+   If the group should not be shown in the title of the link either
+   an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"),
+   or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``").
+
+   Note that no further reST parsing is done in the production, so that you
+   don't have to escape ``*`` or ``|`` characters.
+
+The following is an example taken from the Python Reference Manual::
+
+   .. productionlist::
+      try_stmt: try1_stmt | try2_stmt
+      try1_stmt: "try" ":" `suite`
+               : ("except" [`expression` ["," `target`]] ":" `suite`)+
+               : ["else" ":" `suite`]
+               : ["finally" ":" `suite`]
+      try2_stmt: "try" ":" `suite`
+               : "finally" ":" `suite`
+
+
+.. rubric:: Footnotes
+
+.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
+       directive in the document.
+
+.. [#] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to
+       match any sequence of characters *including* slashes.
+
+.. [#] There is a standard ``.. include`` directive, but it raises errors if the
+       file is not found.  This one only emits a warning.
+
+.. [#] For most builders name and format are the same. At the moment only
+       builders derived from the html builder distinguish between the builder
+       format and the builder name.
+
+       Note that the current builder tag is not available in ``conf.py``, it is
+       only available after the builder is initialized.