summaryrefslogtreecommitdiffstats
path: root/doc/usage/restructuredtext
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage/restructuredtext
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/restructuredtext')
-rw-r--r--doc/usage/restructuredtext/basics.rst631
-rw-r--r--doc/usage/restructuredtext/directives.rst1311
-rw-r--r--doc/usage/restructuredtext/domains.rst2303
-rw-r--r--doc/usage/restructuredtext/field-lists.rst78
-rw-r--r--doc/usage/restructuredtext/index.rst24
-rw-r--r--doc/usage/restructuredtext/roles.rst536
6 files changed, 4883 insertions, 0 deletions
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
new file mode 100644
index 0000000..cc3c615
--- /dev/null
+++ b/doc/usage/restructuredtext/basics.rst
@@ -0,0 +1,631 @@
+.. highlight:: rst
+
+.. _rst-primer:
+
+=======================
+reStructuredText Primer
+=======================
+
+reStructuredText is the default plaintext markup language used by Sphinx. This
+section is a brief introduction to reStructuredText (reST) concepts and syntax,
+intended to provide authors with enough information to author documents
+productively. Since reST was designed to be a simple, unobtrusive markup
+language, this will not take too long.
+
+.. seealso::
+
+ The authoritative `reStructuredText User Documentation
+ <https://docutils.sourceforge.io/rst.html>`_. The "ref" links in this
+ document link to the description of the individual constructs in the reST
+ reference.
+
+
+Paragraphs
+----------
+
+The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST
+document. Paragraphs are simply chunks of text separated by one or more blank
+lines. As in Python, indentation is significant in reST, so all lines of the
+same paragraph must be left-aligned to the same level of indentation.
+
+
+.. _rst-inline-markup:
+
+Inline markup
+-------------
+
+The standard reST inline markup is quite simple: use
+
+* one asterisk: ``*text*`` for emphasis (italics),
+* two asterisks: ``**text**`` for strong emphasis (boldface), and
+* backquotes: ````text```` for code samples.
+
+If asterisks or backquotes appear in running text and could be confused with
+inline markup delimiters, they have to be escaped with a backslash.
+
+Be aware of some restrictions of this markup:
+
+* it may not be nested,
+* content may not start or end with whitespace: ``* text*`` is wrong,
+* it must be separated from surrounding text by non-word characters. Use a
+ backslash escaped space to work around that: ``thisis\ *one*\ word``.
+
+These restrictions may be lifted in future versions of the docutils.
+
+It is also possible to replace or expand upon some of this inline markup with
+roles. Refer to :ref:`rst-roles-alt` for more information.
+
+
+Lists and Quote-like blocks
+---------------------------
+
+List markup (:duref:`ref <bullet-lists>`) is natural: just place an asterisk at
+the start of a paragraph and indent properly. The same goes for numbered
+lists; they can also be autonumbered using a ``#`` sign::
+
+ * This is a bulleted list.
+ * It has two items, the second
+ item uses two lines.
+
+ 1. This is a numbered list.
+ 2. It has two items too.
+
+ #. This is a numbered list.
+ #. It has two items too.
+
+Nested lists are possible, but be aware that they must be separated from the
+parent list items by blank lines::
+
+ * this is
+ * a list
+
+ * with a nested list
+ * and some subitems
+
+ * and here the parent list continues
+
+Definition lists (:duref:`ref <definition-lists>`) are created as follows::
+
+ term (up to a line of text)
+ Definition of the term, which must be indented
+
+ and can even consist of multiple paragraphs
+
+ next term
+ Description.
+
+Note that the term cannot have more than one line of text.
+
+Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
+them more than the surrounding paragraphs.
+
+Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks::
+
+ | These lines are
+ | broken exactly like in
+ | the source file.
+
+There are also several more special blocks available:
+
+* field lists (:duref:`ref <field-lists>`, with caveats noted in
+ :ref:`rst-field-lists`)
+* option lists (:duref:`ref <option-lists>`)
+* quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
+* doctest blocks (:duref:`ref <doctest-blocks>`)
+
+
+.. _rst-literal-blocks:
+
+Literal blocks
+--------------
+
+Literal code blocks (:duref:`ref <literal-blocks>`) are introduced by ending a
+paragraph with the special marker ``::``. The literal block must be indented
+(and, like all paragraphs, separated from the surrounding ones by blank
+lines)::
+
+ This is a normal text paragraph. The next paragraph is a code sample::
+
+ It is not processed in any way, except
+ that the indentation is removed.
+
+ It can span multiple lines.
+
+ This is a normal text paragraph again.
+
+The handling of the ``::`` marker is smart:
+
+* If it occurs as a paragraph of its own, that paragraph is completely left out
+ of the document.
+* If it is preceded by whitespace, the marker is removed.
+* If it is preceded by non-whitespace, the marker is replaced by a single
+ colon.
+
+That way, the second sentence in the above example's first paragraph would be
+rendered as "The next paragraph is a code sample:".
+
+Code highlighting can be enabled for these literal blocks on a document-wide
+basis using the :rst:dir:`highlight` directive and on a project-wide basis
+using the :confval:`highlight_language` configuration option. The
+:rst:dir:`code-block` directive can be used to set highlighting on a
+block-by-block basis. These directives are discussed later.
+
+
+.. _rst-doctest-blocks:
+
+Doctest blocks
+--------------
+
+Doctest blocks (:duref:`ref <doctest-blocks>`) are interactive Python sessions
+cut-and-pasted into docstrings. They do not require the
+:ref:`literal blocks <rst-literal-blocks>` syntax. The doctest block must end
+with a blank line and should *not* end with an unused prompt::
+
+ >>> 1 + 1
+ 2
+
+.. _rst-tables:
+
+Tables
+------
+
+For *grid tables* (:duref:`ref <grid-tables>`), you have to "paint" the cell
+grid yourself. They look like this::
+
+ +------------------------+------------+----------+----------+
+ | Header row, column 1 | Header 2 | Header 3 | Header 4 |
+ | (header rows optional) | | | |
+ +========================+============+==========+==========+
+ | body row 1, column 1 | column 2 | column 3 | column 4 |
+ +------------------------+------------+----------+----------+
+ | body row 2 | ... | ... | |
+ +------------------------+------------+----------+----------+
+
+*Simple tables* (:duref:`ref <simple-tables>`) are easier to write, but
+limited: they must contain more than one row, and the first column cells cannot
+contain multiple lines. They look like this::
+
+ ===== ===== =======
+ A B A and B
+ ===== ===== =======
+ False False False
+ True False False
+ False True False
+ True True True
+ ===== ===== =======
+
+Two more syntaxes are supported: *CSV tables* and *List tables*. They use an
+*explicit markup block*. Refer to :ref:`table-directives` for more information.
+
+
+Hyperlinks
+----------
+
+External links
+~~~~~~~~~~~~~~
+
+Use ```Link text <https://domain.invalid/>`_`` for inline web links. If the
+link text should be the web address, you don't need special markup at all, the
+parser finds links and mail addresses in ordinary text.
+
+.. important:: There must be a space between the link text and the opening \< for the URL.
+
+You can also separate the link and the target definition (:duref:`ref
+<hyperlink-targets>`), like this::
+
+ This is a paragraph that contains `a link`_.
+
+ .. _a link: https://domain.invalid/
+
+Internal links
+~~~~~~~~~~~~~~
+
+Internal linking is done via a special reST role provided by Sphinx, see the
+section on specific markup, :ref:`ref-role`.
+
+
+.. _rst-sections:
+
+Sections
+--------
+
+Section headers (:duref:`ref <sections>`) are created by underlining (and
+optionally overlining) the section title with a punctuation character, at least
+as long as the text::
+
+ =================
+ This is a heading
+ =================
+
+Normally, there are no heading levels assigned to certain characters as the
+structure is determined from the succession of headings. However, this
+convention is used in `Python Developer's Guide for documenting
+<https://devguide.python.org/documentation/markup/#sections>`_ which you may
+follow:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=`` for sections
+* ``-`` for subsections
+* ``^`` for subsubsections
+* ``"`` for paragraphs
+
+Of course, you are free to use your own marker characters (see the reST
+documentation), and use a deeper nesting level, but keep in mind that most
+target formats (HTML, LaTeX) have a limited supported nesting depth.
+
+
+.. _rst-field-lists:
+
+Field Lists
+-----------
+
+Field lists (:duref:`ref <field-lists>`) are sequences of fields marked up like
+this::
+
+ :fieldname: Field content
+
+They are commonly used in Python documentation::
+
+ def my_function(my_arg, my_other_arg):
+ """A function just for me.
+
+ :param my_arg: The first of my arguments.
+ :param my_other_arg: The second of my arguments.
+
+ :returns: A message (just for me, of course).
+ """
+
+Sphinx extends standard docutils behavior and intercepts field lists specified
+at the beginning of documents. Refer to :doc:`field-lists` for more
+information.
+
+
+.. TODO This ref should be 'rst-roles', but that already exists. Rename the
+.. other ones
+
+.. _rst-roles-alt:
+
+Roles
+-----
+
+A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline
+piece of explicit markup. It signifies that the enclosed text should be
+interpreted in a specific way. Sphinx uses this to provide semantic markup and
+cross-referencing of identifiers, as described in the appropriate section. The
+general syntax is ``:rolename:`content```.
+
+Docutils supports the following roles:
+
+* :durole:`emphasis` -- equivalent of ``*emphasis*``
+* :durole:`strong` -- equivalent of ``**strong**``
+* :durole:`literal` -- equivalent of ````literal````
+* :durole:`subscript` -- subscript text
+* :durole:`superscript` -- superscript text
+* :durole:`title-reference` -- for titles of books, periodicals, and other
+ materials
+
+Refer to :doc:`roles` for roles added by Sphinx.
+
+
+Explicit Markup
+---------------
+
+"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for
+most constructs that need special handling, such as footnotes,
+specially-highlighted paragraphs, comments, and generic directives.
+
+An explicit markup block begins with a line starting with ``..`` followed by
+whitespace and is terminated by the next paragraph at the same level of
+indentation. (There needs to be a blank line between explicit markup and
+normal paragraphs. This may all sound a bit complicated, but it is intuitive
+enough when you write it.)
+
+
+.. _rst-directives:
+
+Directives
+----------
+
+A directive (:duref:`ref <directives>`) is a generic block of explicit markup.
+Along with roles, it is one of the extension mechanisms of reST, and Sphinx
+makes heavy use of it.
+
+Docutils supports the following directives:
+
+* Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
+ :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
+ :dudir:`tip`, :dudir:`warning` and the generic
+ :dudir:`admonition <admonitions>`. (Most themes style only "note" and
+ "warning" specially.)
+
+* Images:
+
+ - :dudir:`image` (see also Images_ below)
+ - :dudir:`figure` (an image with caption and optional legend)
+
+* Additional body elements:
+
+ - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file
+ only, table of contents)
+ - :dudir:`container` (a container with a custom class, useful to generate an
+ outer ``<div>`` in HTML)
+ - :dudir:`rubric` (a heading without relation to the document sectioning)
+ - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements)
+ - :dudir:`parsed-literal` (literal block that supports inline markup)
+ - :dudir:`epigraph` (a block quote with optional attribution line)
+ - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own
+ class attribute)
+ - :dudir:`compound <compound-paragraph>` (a compound paragraph)
+
+* Special tables:
+
+ - :dudir:`table` (a table with title)
+ - :dudir:`csv-table` (a table generated from comma-separated values)
+ - :dudir:`list-table` (a table generated from a list of lists)
+
+* Special directives:
+
+ - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup)
+ - :dudir:`include` (include reStructuredText from another file) -- in Sphinx,
+ when given an absolute include file path, this directive takes it as
+ relative to the source directory
+
+ .. _rstclass:
+
+ - :dudir:`class` (assign a class attribute to the next element)
+
+ .. note::
+
+ When the default domain contains a ``class`` directive, this directive
+ will be shadowed. Therefore, Sphinx re-exports it as ``rst-class``.
+
+* HTML specifics:
+
+ - :dudir:`meta`
+ (generation of HTML ``<meta>`` tags, see also :ref:`html-meta` below)
+ - :dudir:`title <metadata-document-title>` (override document title)
+
+* Influencing markup:
+
+ - :dudir:`default-role` (set a new default role)
+ - :dudir:`role` (create a new role)
+
+ Since these are only per-file, better use Sphinx's facilities for setting the
+ :confval:`default_role`.
+
+.. warning::
+
+ Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
+ :dudir:`footer`.
+
+Directives added by Sphinx are described in :doc:`directives`.
+
+Basically, a directive consists of a name, arguments, options and content.
+(Keep this terminology in mind, it is used in the next chapter describing
+custom directives.) Looking at this example, ::
+
+ .. function:: foo(x)
+ foo(y, z)
+ :module: some.module.name
+
+ Return a line of text input from the user.
+
+``function`` is the directive name. It is given two arguments here, the
+remainder of the first line and the second line, as well as one option
+``module`` (as you can see, options are given in the lines immediately
+following the arguments and indicated by the colons). Options must be indented
+to the same level as the directive content.
+
+The directive content follows after a blank line and is indented relative to
+the directive start or if options are present, by the same amount as the
+options.
+
+Be careful as the indent is not a fixed number of whitespace, e.g. three, but
+any number whitespace. This can be surprising when a fixed indent is used
+throughout the document and can make a difference for directives which are
+sensitive to whitespace. Compare::
+
+ .. code-block::
+ :caption: A cool example
+
+ The output of this line starts with four spaces.
+
+ .. code-block::
+
+ The output of this line has no spaces at the beginning.
+
+In the first code block, the indent for the content was fixated by the option
+line to three spaces, consequently the content starts with four spaces.
+In the latter the indent was fixed by the content itself to seven spaces, thus
+it does not start with a space.
+
+
+Images
+------
+
+reST supports an image directive (:dudir:`ref <image>`), used like so::
+
+ .. image:: gnu.png
+ (options)
+
+When used within Sphinx, the file name given (here ``gnu.png``) must either be
+relative to the source file, or absolute which means that they are relative to
+the top source directory. For example, the file ``sketch/spam.rst`` could
+refer to the image ``images/spam.png`` as ``../images/spam.png`` or
+``/images/spam.png``.
+
+Sphinx will automatically copy image files over to a subdirectory of the output
+directory on building (e.g. the ``_static`` directory for HTML output.)
+
+Interpretation of image size options (``width`` and ``height``) is as follows:
+if the size has no unit or the unit is pixels, the given size will only be
+respected for output channels that support pixels. Other units (like ``pt`` for
+points) will be used for HTML and LaTeX output (the latter replaces ``pt`` by
+``bp`` as this is the TeX unit such that ``72bp=1in``).
+
+Sphinx extends the standard docutils behavior by allowing an asterisk for the
+extension::
+
+ .. image:: gnu.*
+
+Sphinx then searches for all images matching the provided pattern and
+determines their type. Each builder then chooses the best image out of these
+candidates. For instance, if the file name ``gnu.*`` was given and two files
+:file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX
+builder would choose the former, while the HTML builder would prefer the
+latter. Supported image types and choosing priority are defined at
+:doc:`/usage/builders/index`.
+
+Note that image file names should not contain spaces.
+
+.. versionchanged:: 0.4
+ Added the support for file names ending in an asterisk.
+
+.. versionchanged:: 0.6
+ Image paths can now be absolute.
+
+.. versionchanged:: 1.5
+ latex target supports pixels (default is ``96px=1in``).
+
+
+Footnotes
+---------
+
+For footnotes (:duref:`ref <footnotes>`), use ``[#name]_`` to mark the footnote
+location, and add the footnote body at the bottom of the document after a
+"Footnotes" rubric heading, like so::
+
+ Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
+
+ .. rubric:: Footnotes
+
+ .. [#f1] Text of the first footnote.
+ .. [#f2] Text of the second footnote.
+
+You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
+footnotes without names (``[#]_``).
+
+
+Citations
+---------
+
+Standard reST citations (:duref:`ref <citations>`) are supported, with the
+additional feature that they are "global", i.e. all citations can be referenced
+from all files. Use them like so::
+
+ Lorem ipsum [Ref]_ dolor sit amet.
+
+ .. [Ref] Book or article reference, URL or whatever.
+
+Citation usage is similar to footnote usage, but with a label that is not
+numeric or begins with ``#``.
+
+
+Substitutions
+-------------
+
+reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which
+are pieces of text and/or markup referred to in the text by ``|name|``. They
+are defined like footnotes with explicit markup blocks, like this::
+
+ .. |name| replace:: replacement *text*
+
+or this::
+
+ .. |caution| image:: warning.png
+ :alt: Warning!
+
+See the :duref:`reST reference for substitutions <substitution-definitions>`
+for details.
+
+.. index:: ! pair: global; substitutions
+
+If you want to use some substitutions for all documents, put them into
+:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
+and include it into all documents you want to use them in, using the
+:dudir:`include` directive. (Be sure to give the include file a file name
+extension differing from that of other source files, to avoid Sphinx finding it
+as a standalone document.)
+
+Sphinx defines some default substitutions, see :ref:`default-substitutions`.
+
+
+Comments
+--------
+
+Every explicit markup block which isn't a valid markup construct (like the
+footnotes above) is regarded as a comment (:duref:`ref <comments>`). For
+example::
+
+ .. This is a comment.
+
+You can indent text after a comment start to form multiline comments::
+
+ ..
+ This whole indented block
+ is a comment.
+
+ Still in the comment.
+
+
+.. _html-meta:
+
+HTML Metadata
+-------------
+
+The :dudir:`meta` directive allows specifying the HTML
+`metadata element`_ of a Sphinx documentation page. For example, the
+directive::
+
+ .. meta::
+ :description: The Sphinx documentation builder
+ :keywords: Sphinx, documentation, builder
+
+will generate the following HTML output:
+
+.. code:: html
+
+ <meta name="description" content="The Sphinx documentation builder">
+ <meta name="keywords" content="Sphinx, documentation, builder">
+
+Also, Sphinx will add the keywords as specified in the meta directive to the
+search index. Thereby, the ``lang`` attribute of the meta element is
+considered. For example, the directive::
+
+ .. meta::
+ :keywords: backup
+ :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
+ :keywords lang=de: bittediesenkeyfinden
+
+adds the following words to the search indices of builds with different language
+configurations:
+
+* ``pleasefindthiskey``, ``pleasefindthiskeytoo`` to *English* builds;
+* ``bittediesenkeyfinden`` to *German* builds;
+* ``backup`` to builds in all languages.
+
+.. _metadata element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
+
+
+Source encoding
+---------------
+
+Since the easiest way to include special characters like em dashes or copyright
+signs in reST is to directly write them as Unicode characters, one has to
+specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by
+default; you can change this with the :confval:`source_encoding` config value.
+
+
+Gotchas
+-------
+
+There are some problems one commonly runs into while authoring reST documents:
+
+* **Separation of inline markup:** As said above, inline markup spans must be
+ separated from the surrounding text by non-word characters, you have to use a
+ backslash-escaped space to get around that. See :duref:`the reference
+ <substitution-definitions>` for the details.
+
+* **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
+ possible.
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.
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
new file mode 100644
index 0000000..729e651
--- /dev/null
+++ b/doc/usage/restructuredtext/domains.rst
@@ -0,0 +1,2303 @@
+.. highlight:: rst
+
+=======
+Domains
+=======
+
+.. versionadded:: 1.0
+
+Originally, Sphinx was conceived for a single project, the documentation of the
+Python language. Shortly afterwards, it was made available for everyone as a
+documentation tool, but the documentation of Python modules remained deeply
+built in -- the most fundamental directives, like ``function``, were designed
+for Python objects. Since Sphinx has become somewhat popular, interest
+developed in using it for many different purposes: C/C++ projects, JavaScript,
+or even reStructuredText markup (like in this documentation).
+
+While this was always possible, it is now much easier to easily support
+documentation of projects using different programming languages or even ones
+not supported by the main Sphinx distribution, by providing a **domain** for
+every such purpose.
+
+A domain is a collection of markup (reStructuredText :term:`directive`\ s and
+:term:`role`\ s) to describe and link to :term:`object`\ s belonging together,
+e.g. elements of a programming language. Directive and role names in a domain
+have names like ``domain:name``, e.g. ``py:function``. Domains can also
+provide custom indices (like the Python Module Index).
+
+Having domains means that there are no naming problems when one set of
+documentation wants to refer to e.g. C++ and Python classes. It also means
+that extensions that support the documentation of whole new languages are much
+easier to write.
+
+This section describes what the domains that are included with Sphinx provide.
+The domain API is documented as well, in the section :ref:`domain-api`.
+
+
+.. _basic-domain-markup:
+
+Basic Markup
+------------
+
+Most domains provide a number of :dfn:`object description directives`, used to
+describe specific objects provided by modules. Each directive requires one or
+more signatures to provide basic information about what is being described, and
+the content should be the description.
+
+A domain will typically keep an internal index of all entities to aid
+cross-referencing.
+Typically it will also add entries in the shown general index.
+If you want to suppress the addition of an entry in the shown index, you can
+give the directive option flag ``:no-index-entry:``.
+If you want to exclude the object description from the table of contents, you
+can give the directive option flag ``:no-contents-entry:``.
+If you want to typeset an object description, without even making it available
+for cross-referencing, you can give the directive option flag ``:no-index:``
+(which implies ``:no-index-entry:``).
+If you do not want to typeset anything, you can give the directive option flag
+``:no-typesetting:``. This can for example be used to create only a target and
+index entry for later reference.
+Though, note that not every directive in every domain may support these
+options.
+
+.. versionadded:: 3.2
+ The directive option ``noindexentry`` in the Python, C, C++, and Javascript
+ domains.
+
+.. versionadded:: 5.2.3
+ The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript,
+ and reStructuredText domains.
+
+.. versionadded:: 7.2
+ The directive option ``no-typesetting`` in the Python, C, C++, Javascript,
+ and reStructuredText domains.
+
+.. versionchanged:: 7.2
+
+ * The directive option ``:noindex:`` was renamed
+ to ``:no-index:``.
+ * The directive option ``:noindexentry:`` was renamed
+ to ``:no-index-entry:``.
+ * The directive option ``:nocontentsentry:`` was renamed
+ to ``:no-contents-entry:``.
+
+ The previous names are retained as aliases,
+ but will be deprecated and removed
+ in a future version of Sphinx.
+
+An example using a Python domain directive::
+
+ .. py:function:: spam(eggs)
+ ham(eggs)
+
+ Spam or ham the foo.
+
+This describes the two Python functions ``spam`` and ``ham``. (Note that when
+signatures become too long, you can break them if you add a backslash to lines
+that are continued in the next line. Example::
+
+ .. py:function:: filterwarnings(action, message='', category=Warning, \
+ module='', lineno=0, append=False)
+ :no-index:
+
+(This example also shows how to use the ``:no-index:`` flag.)
+
+The domains also provide roles that link back to these object descriptions.
+For example, to link to one of the functions described in the example above,
+you could say ::
+
+ The function :py:func:`spam` does a similar thing.
+
+As you can see, both directive and role names contain the domain name and the
+directive name.
+
+The directive option ``:no-typesetting:`` can be used to create a target
+(and index entry) which can later be referenced
+by the roles provided by the domain.
+This is particularly useful for literate programming:
+
+.. code-block:: rst
+
+ .. py:function:: spam(eggs)
+ :no-typesetting:
+
+ .. code::
+
+ def spam(eggs):
+ pass
+
+ The function :py:func:`spam` does nothing.
+
+.. rubric:: Default Domain
+
+For documentation describing objects from solely one domain, authors will not
+have to state again its name at each directive, role, etc... after
+having specified a default. This can be done either via the config
+value :confval:`primary_domain` or via this directive:
+
+.. rst:directive:: .. default-domain:: name
+
+ Select a new default domain. While the :confval:`primary_domain` selects a
+ global default, this only has an effect within the same file.
+
+If no other default is selected, the Python domain (named ``py``) is the
+default one, mostly for compatibility with documentation written for older
+versions of Sphinx.
+
+Directives and roles that belong to the default domain can be mentioned without
+giving the domain name, i.e. ::
+
+ .. function:: pyfunc()
+
+ Describes a Python function.
+
+ Reference to :func:`pyfunc`.
+
+Cross-referencing syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cross-reference roles provided by domains, the same facilities exist as for
+general cross-references. See :ref:`xref-syntax`.
+
+In short:
+
+* You may supply an explicit title and reference target: ``:role:`title
+ <target>``` will refer to *target*, but the link text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+ component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will
+ refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+.. _python-domain:
+
+The Python Domain
+-----------------
+
+The Python domain (name **py**) provides the following directives for module
+declarations:
+
+.. rst:directive:: .. py:module:: name
+
+ This directive marks the beginning of the description of a module (or package
+ submodule, in which case the name should be fully qualified, including the
+ package name). A description of the module such as the docstring can be
+ placed in the body of the directive.
+
+ This directive will also cause an entry in the global module index.
+
+ .. versionchanged:: 5.2
+
+ Module directives support body content.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: platform: platforms
+ :type: comma separated list
+
+ Indicate platforms which the module is available (if it is available on
+ all platforms, the option should be omitted). The keys are short
+ identifiers; examples that are in use include "IRIX", "Mac", "Windows"
+ and "Unix". It is important to use a key which has already been used when
+ applicable.
+
+ .. rst:directive:option:: synopsis: purpose
+ :type: text
+
+ Consist of one sentence describing the module's purpose -- it is currently
+ only used in the Global Module Index.
+
+ .. rst:directive:option:: deprecated
+ :type: no argument
+
+ Mark a module as deprecated; it will be designated as such in various
+ locations then.
+
+
+
+.. rst:directive:: .. py:currentmodule:: name
+
+ This directive tells Sphinx that the classes, functions etc. documented from
+ here are in the given module (like :rst:dir:`py:module`), but it will not
+ create index entries, an entry in the Global Module Index, or a link target
+ for :rst:role:`py:mod`. This is helpful in situations where documentation
+ for things in a module is spread over multiple files or sections -- one
+ location has the :rst:dir:`py:module` directive, the others only
+ :rst:dir:`py:currentmodule`.
+
+The following directives are provided for module and class contents:
+
+.. rst:directive:: .. py:function:: name(parameters)
+ .. py:function:: name[type parameters](parameters)
+
+ Describes a module-level function.
+ The signature should include the parameters,
+ together with optional type parameters,
+ as given in the Python function definition, see :ref:`signatures`.
+ For example::
+
+ .. py:function:: Timer.repeat(repeat=3, number=1_000_000)
+ .. py:function:: add[T](a: T, b: T) -> T
+
+ For methods you should use :rst:dir:`py:method`.
+
+ The description normally includes information about the parameters required
+ and how they are used (especially whether mutable objects passed as
+ parameters are modified), side effects, and possible exceptions.
+
+ This information can (in any ``py`` directive) optionally be given in a
+ structured form, see :ref:`info-field-lists`.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: async
+ :type: no value
+
+ Indicate the function is an async function.
+
+ .. versionadded:: 2.1
+
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's arguments will be emitted on a single logical
+ line, overriding :confval:`python_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+ .. rst:directive:option:: single-line-type-parameter-list
+ :type: no value
+
+ Ensure that the function's type parameters are emitted on a single
+ logical line, overriding :confval:`python_maximum_signature_line_length`
+ and :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+
+.. rst:directive:: .. py:data:: name
+
+ Describes global data in a module, including both variables and values used
+ as "defined constants." Class and object attributes are not documented
+ using this environment.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: type: type of the variable
+ :type: text
+
+ .. versionadded:: 2.4
+
+ .. rst:directive:option:: value: initial value of the variable
+ :type: text
+
+ .. versionadded:: 2.4
+
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:exception:: name
+ .. py:exception:: name(parameters)
+ .. py:exception:: name[type parmeters](parameters)
+
+ Describes an exception class.
+ The signature can, but need not include parentheses with constructor arguments,
+ or may optionally include type parameters (see :pep:`695`).
+
+ .. rubric:: options
+
+ .. rst:directive:option:: final
+ :type: no value
+
+ Indicate the class is a final class.
+
+ .. versionadded:: 3.1
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ See :rst:dir:`py:class:single-line-parameter-list`.
+
+ .. versionadded:: 7.1
+
+ .. rst:directive:option:: single-line-type-parameter-list
+ :type: no value
+
+ See :rst:dir:`py:class:single-line-type-parameter-list`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. py:class:: name
+ .. py:class:: name(parameters)
+ .. py:class:: name[type parmeters](parameters)
+
+ Describes a class.
+ The signature can optionally include type parameters (see :pep:`695`)
+ or parentheses with parameters which will be shown as the constructor arguments.
+ See also :ref:`signatures`.
+
+ Methods and attributes belonging to the class should be placed in this
+ directive's body. If they are placed outside, the supplied name should
+ contain the class name so that cross-references still work. Example::
+
+ .. py:class:: Foo
+
+ .. py:method:: quux()
+
+ -- or --
+
+ .. py:class:: Bar
+
+ .. py:method:: Bar.quux()
+
+ The first way is the preferred one.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
+ .. rst:directive:option:: final
+ :type: no value
+
+ Indicate the class is a final class.
+
+ .. versionadded:: 3.1
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the class constructor's arguments will be emitted on a single
+ logical line, overriding :confval:`python_maximum_signature_line_length`
+ and :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+ .. rst:directive:option:: single-line-type-parameter-list
+ :type: no value
+
+ Ensure that the class type parameters are emitted on a single logical
+ line, overriding :confval:`python_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+.. rst:directive:: .. py:attribute:: name
+
+ Describes an object data attribute. The description should include
+ information about the type of the data to be expected and whether it may be
+ changed directly.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: type: type of the attribute
+ :type: text
+
+ .. versionadded:: 2.4
+
+ .. rst:directive:option:: value: initial value of the attribute
+ :type: text
+
+ .. versionadded:: 2.4
+
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:property:: name
+
+ Describes an object property.
+
+ .. versionadded:: 4.0
+
+ .. rubric:: options
+
+ .. rst:directive:option:: abstractmethod
+ :type: no value
+
+ Indicate the property is abstract.
+
+ .. rst:directive:option:: classmethod
+ :type: no value
+
+ Indicate the property is a classmethod.
+
+ .. versionaddedd: 4.2
+
+ .. rst:directive:option:: type: type of the property
+ :type: text
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:method:: name(parameters)
+ .. py:method:: name[type parameters](parameters)
+
+ Describes an object method. The parameters should not include the ``self``
+ parameter. The description should include similar information to that
+ described for ``function``. See also :ref:`signatures` and
+ :ref:`info-field-lists`.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: abstractmethod
+ :type: no value
+
+ Indicate the method is an abstract method.
+
+ .. versionadded:: 2.1
+
+ .. rst:directive:option:: async
+ :type: no value
+
+ Indicate the method is an async method.
+
+ .. versionadded:: 2.1
+
+ .. rst:directive:option:: canonical
+ :type: full qualified name including module name
+
+ Describe the location where the object is defined if the object is
+ imported from other modules
+
+ .. versionadded:: 4.0
+
+ .. rst:directive:option:: classmethod
+ :type: no value
+
+ Indicate the method is a class method.
+
+ .. versionadded:: 2.1
+
+ .. rst:directive:option:: final
+ :type: no value
+
+ Indicate the class is a final method.
+
+ .. versionadded:: 3.1
+
+ .. rst::directive:option:: module
+ :type: text
+
+ Describe the location where the object is defined. The default value is
+ the module specified by :rst:dir:`py:currentmodule`.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the method's arguments will be emitted on a single logical
+ line, overriding :confval:`python_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+ .. rst:directive:option:: single-line-type-parameter-list
+ :type: no value
+
+ Ensure that the method's type parameters are emitted on a single logical
+ line, overriding :confval:`python_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.2
+
+ .. rst:directive:option:: staticmethod
+ :type: no value
+
+ Indicate the method is a static method.
+
+ .. versionadded:: 2.1
+
+
+.. rst:directive:: .. py:staticmethod:: name(parameters)
+ .. py:staticmethod:: name[type parameters](parameters)
+
+ Like :rst:dir:`py:method`, but indicates that the method is a static method.
+
+ .. versionadded:: 0.4
+
+.. rst:directive:: .. py:classmethod:: name(parameters)
+ .. py:classmethod:: name[type parameters](parameters)
+
+ Like :rst:dir:`py:method`, but indicates that the method is a class method.
+
+ .. versionadded:: 0.6
+
+.. rst:directive:: .. py:decorator:: name
+ .. py:decorator:: name(parameters)
+ .. py:decorator:: name[type parameters](parameters)
+
+ Describes a decorator function. The signature should represent the usage as
+ a decorator. For example, given the functions
+
+ .. code-block:: python
+
+ def removename(func):
+ func.__name__ = ''
+ return func
+
+ def setnewname(name):
+ def decorator(func):
+ func.__name__ = name
+ return func
+ return decorator
+
+ the descriptions should look like this::
+
+ .. py:decorator:: removename
+
+ Remove name of the decorated function.
+
+ .. py:decorator:: setnewname(name)
+
+ Set name of the decorated function to *name*.
+
+ (as opposed to ``.. py:decorator:: removename(func)``.)
+
+ There is no ``py:deco`` role to link to a decorator that is marked up with
+ this directive; rather, use the :rst:role:`py:func` role.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the decorator's arguments will be emitted on a single logical
+ line, overriding :confval:`python_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+ .. rst:directive:option:: single-line-type-parameter-list
+ :type: no value
+
+ Ensure that the decorator's type parameters are emitted on a single
+ logical line, overriding :confval:`python_maximum_signature_line_length`
+ and :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.2
+
+.. rst:directive:: .. py:decoratormethod:: name
+ .. py:decoratormethod:: name(signature)
+ .. py:decoratormethod:: name[type parameters](signature)
+
+ Same as :rst:dir:`py:decorator`, but for decorators that are methods.
+
+ Refer to a decorator method using the :rst:role:`py:meth` role.
+
+.. _signatures:
+
+Python Signatures
+~~~~~~~~~~~~~~~~~
+
+Signatures of functions, methods and class constructors can be given like they
+would be written in Python.
+
+Default values for optional arguments can be given (but if they contain commas,
+they will confuse the signature parser). Python 3-style argument annotations
+can also be given as well as return type annotations::
+
+ .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+
+For functions with optional parameters that don't have default values
+(typically functions implemented in C extension modules without keyword
+argument support), you can use brackets to specify the optional parts:
+
+.. py:function:: compile(source[, filename[, symbol]])
+ :no-index:
+
+It is customary to put the opening bracket before the comma.
+
+Python 3.12 introduced *type parameters*, which are type variables
+declared directly within the class or function definition:
+
+.. code:: python
+
+ class AnimalList[AnimalT](list[AnimalT]):
+ ...
+
+ def add[T](a: T, b: T) -> T:
+ return a + b
+
+The corresponding reStructuredText documentation would be:
+
+.. code:: rst
+
+ .. py:class:: AnimalList[AnimalT]
+
+ .. py:function:: add[T](a: T, b: T) -> T
+
+See :pep:`695` and :pep:`696` for details and the full specification.
+
+.. _info-field-lists:
+
+Info field lists
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.4
+.. versionchanged:: 3.0
+
+ meta fields are added.
+
+Inside Python object description directives, reST field lists with these fields
+are recognized and formatted nicely:
+
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
+ Description of a parameter.
+* ``type``: Type of a parameter. Creates a link if possible.
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
+ exception is raised.
+* ``var``, ``ivar``, ``cvar``: Description of a variable.
+* ``vartype``: Type of a variable. Creates a link if possible.
+* ``returns``, ``return``: Description of the return value.
+* ``rtype``: Return type. Creates a link if possible.
+* ``meta``: Add metadata to description of the python object. The metadata will
+ not be shown on output document. For example, ``:meta private:`` indicates
+ the python object is private member. It is used in
+ :py:mod:`sphinx.ext.autodoc` for filtering members.
+
+.. note::
+
+ In current release, all ``var``, ``ivar`` and ``cvar`` are represented as
+ "Variable". There is no difference at all.
+
+The field names must consist of one of these keywords and an argument (except
+for ``returns`` and ``rtype``, which do not need an argument). This is best
+explained by an example::
+
+ .. py:function:: send_message(sender, recipient, message_body, [priority=1])
+
+ Send a message to a recipient
+
+ :param str sender: The person sending the message
+ :param str recipient: The recipient of the message
+ :param str message_body: The body of the message
+ :param priority: The priority of the message, can be a number 1-5
+ :type priority: integer or None
+ :return: the message id
+ :rtype: int
+ :raises ValueError: if the message_body exceeds 160 characters
+ :raises TypeError: if the message_body is not a basestring
+
+This will render like this:
+
+.. py:function:: send_message(sender, recipient, message_body, [priority=1])
+ :no-index:
+
+ Send a message to a recipient
+
+ :param str sender: The person sending the message
+ :param str recipient: The recipient of the message
+ :param str message_body: The body of the message
+ :param priority: The priority of the message, can be a number 1-5
+ :type priority: int or None
+ :return: the message id
+ :rtype: int
+ :raises ValueError: if the message_body exceeds 160 characters
+ :raises TypeError: if the message_body is not a basestring
+
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+ :param int priority: The priority of the message, can be a number 1-5
+
+.. versionadded:: 1.5
+
+Container types such as lists and dictionaries can be linked automatically
+using the following syntax::
+
+ :type priorities: list(int)
+ :type priorities: list[int]
+ :type mapping: dict(str, int)
+ :type mapping: dict[str, int]
+ :type point: tuple(float, float)
+ :type point: tuple[float, float]
+
+Multiple types in a type field will be linked automatically if separated by the
+word "or"::
+
+ :type an_arg: int or None
+ :vartype a_var: str or int
+ :rtype: float or str
+
+.. _python-roles:
+
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. rst:role:: py:mod
+
+ Reference a module; a dotted name may be used. This should also be used for
+ package names.
+
+.. rst:role:: py:func
+
+ Reference a Python function; dotted names may be used. The role text needs
+ not include trailing parentheses to enhance readability; they will be added
+ automatically by Sphinx if the :confval:`add_function_parentheses` config
+ value is ``True`` (the default).
+
+.. rst:role:: py:data
+
+ Reference a module-level variable.
+
+.. rst:role:: py:const
+
+ Reference a "defined" constant. This may be a Python variable that is not
+ intended to be changed.
+
+.. rst:role:: py:class
+
+ Reference a class; a dotted name may be used.
+
+.. rst:role:: py:meth
+
+ Reference a method of an object. The role text can include the type name
+ and the method name; if it occurs within the description of a type, the type
+ name can be omitted. A dotted name may be used.
+
+.. rst:role:: py:attr
+
+ Reference a data attribute of an object.
+
+ .. note:: The role is also able to refer to property.
+
+.. rst:role:: py:exc
+
+ Reference an exception. A dotted name may be used.
+
+.. rst:role:: py:obj
+
+ Reference an object of unspecified type. Useful e.g. as the
+ :confval:`default_role`.
+
+ .. versionadded:: 0.4
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:py:func:`filter``` could refer to a function named ``filter``
+in the current module, or the built-in function of that name. In contrast,
+``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
+``foo`` module.
+
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended. If you prefix the name with
+a dot, this order is reversed. For example, in the documentation of Python's
+:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
+function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
+
+A similar heuristic is used to determine whether the name is an attribute of
+the currently documented class.
+
+Also, if the name is prefixed with a dot, and no exact match is found, the
+target is taken as a suffix and all object names with that suffix are searched.
+For example, ``:py:meth:`.TarFile.close``` references the
+``tarfile.TarFile.close()`` function, even if the current module is not
+``tarfile``. Since this can get ambiguous, if there is more than one possible
+match, you will get a warning from Sphinx.
+
+Note that you can combine the ``~`` and ``.`` prefixes:
+``:py:meth:`~.TarFile.close``` will reference the ``tarfile.TarFile.close()``
+method, but the visible link caption will only be ``close()``.
+
+
+.. _c-domain:
+
+The C Domain
+------------
+
+The C domain (name **c**) is suited for documentation of C API.
+
+.. rst:directive:: .. c:member:: declaration
+ .. c:var:: declaration
+
+ Describes a C struct member or variable. Example signature::
+
+ .. c:member:: PyObject *PyTypeObject.tp_bases
+
+ The difference between the two directives is only cosmetic.
+
+.. rst:directive:: .. c:function:: function prototype
+
+ Describes a C function. The signature should be given as in C, e.g.::
+
+ .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ Note that you don't have to backslash-escape asterisks in the signature, as
+ it is not parsed by the reST inliner.
+
+ In the description of a function you can use the following info fields
+ (see also :ref:`info-field-lists`).
+
+ * ``param``, ``parameter``, ``arg``, ``argument``,
+ Description of a parameter.
+ * ``type``: Type of a parameter,
+ written as if passed to the :rst:role:`c:expr` role.
+ * ``returns``, ``return``: Description of the return value.
+ * ``rtype``: Return type,
+ written as if passed to the :rst:role:`c:expr` role.
+ * ``retval``, ``retvals``: An alternative to ``returns`` for describing
+ the result of the function.
+
+ .. versionadded:: 4.3
+ The ``retval`` field type.
+
+ For example::
+
+ .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ :param type: description of the first parameter.
+ :param nitems: description of the second parameter.
+ :returns: a result.
+ :retval NULL: under some conditions.
+ :retval NULL: under some other conditions as well.
+
+ which renders as
+
+ .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+ ..
+ ** for some editors (e.g., vim) to stop bold-highlighting the source
+
+ :param type: description of the first parameter.
+ :param nitems: description of the second parameter.
+ :returns: a result.
+ :retval NULL: under some conditions.
+ :retval NULL: under some other conditions as well.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`c_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+
+.. rst:directive:: .. c:macro:: name
+ .. c:macro:: name(arg list)
+
+ Describes a C macro, i.e., a C-language ``#define``, without the replacement
+ text.
+
+ In the description of a macro you can use the same info fields as for the
+ :rst:dir:`c:function` directive.
+
+ .. versionadded:: 3.0
+ The function style variant.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the macro's parameters will be emitted on a single logical
+ line, overriding :confval:`c_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. c:struct:: name
+
+ Describes a C struct.
+
+ .. versionadded:: 3.0
+
+.. rst:directive:: .. c:union:: name
+
+ Describes a C union.
+
+ .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enum:: name
+
+ Describes a C enum.
+
+ .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enumerator:: name
+
+ Describes a C enumerator.
+
+ .. versionadded:: 3.0
+
+.. rst:directive:: .. c:type:: typedef-like declaration
+ .. c:type:: name
+
+ Describes a C type, either as a typedef, or the alias for an unspecified
+ type.
+
+.. _c-roles:
+
+Cross-referencing C constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles create cross-references to C-language constructs if they
+are defined in the documentation:
+
+.. rst:role:: c:member
+ c:data
+ c:var
+ c:func
+ c:macro
+ c:struct
+ c:union
+ c:enum
+ c:enumerator
+ c:type
+
+ Reference a C declaration, as defined above.
+ Note that :rst:role:`c:member`, :rst:role:`c:data`, and
+ :rst:role:`c:var` are equivalent.
+
+ .. versionadded:: 3.0
+ The var, struct, union, enum, and enumerator roles.
+
+
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C supports anonymous structs, enums, and unions.
+For the sake of documentation they must be given some name that starts with
+``@``, e.g., ``@42`` or ``@data``.
+These names can also be used in cross-references,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
+link).
+
+Example::
+
+ .. c:struct:: Data
+
+ .. c:union:: @data
+
+ .. c:var:: int a
+
+ .. c:var:: double b
+
+ Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+This will be rendered as:
+
+.. c:struct:: Data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:union:: @data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:var:: int a
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:var:: double b
+ :no-contents-entry:
+ :no-index-entry:
+
+Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+.. versionadded:: 3.0
+
+
+Aliasing Declarations
+~~~~~~~~~~~~~~~~~~~~~
+
+.. c:namespace-push:: @alias
+
+Sometimes it may be helpful list declarations elsewhere than their main
+documentation, e.g., when creating a synopsis of an interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. c:alias:: name
+
+ Insert one or more alias declarations. Each entity can be specified
+ as they can in the :rst:role:`c:any` role.
+
+ For example::
+
+ .. c:var:: int data
+ .. c:function:: int f(double k)
+
+ .. c:alias:: data
+ f
+
+ becomes
+
+ .. c:var:: int data
+ .. c:function:: int f(double k)
+
+ .. c:alias:: data
+ f
+
+ .. versionadded:: 3.2
+
+
+ .. rubric:: Options
+
+ .. rst:directive:option:: maxdepth: int
+
+ Insert nested declarations as well, up to the total depth given.
+ Use 0 for infinite depth and 1 for just the mentioned declaration.
+ Defaults to 1.
+
+ .. versionadded:: 3.3
+
+ .. rst:directive:option:: noroot
+
+ Skip the mentioned declarations and only render nested declarations.
+ Requires ``maxdepth`` either 0 or at least 2.
+
+ .. versionadded:: 3.5
+
+
+.. c:namespace-pop::
+
+
+Inline Expressions and Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: c:expr
+ c:texpr
+
+ Insert a C expression or type either as inline code (``cpp:expr``)
+ or inline text (``cpp:texpr``). For example::
+
+ .. c:var:: int a = 42
+
+ .. c:function:: int f(int i)
+
+ An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
+
+ A type: :c:expr:`const Data*`
+ (or as text :c:texpr:`const Data*`).
+
+ will be rendered as follows:
+
+ .. c:var:: int a = 42
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. c:function:: int f(int i)
+ :no-contents-entry:
+ :no-index-entry:
+
+ An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
+
+ A type: :c:expr:`const Data*`
+ (or as text :c:texpr:`const Data*`).
+
+ .. versionadded:: 3.0
+
+
+Namespacing
+~~~~~~~~~~~
+
+.. versionadded:: 3.1
+
+The C language it self does not support namespacing, but it can sometimes be
+useful to emulate it in documentation, e.g., to show alternate declarations.
+The feature may also be used to document members of structs/unions/enums
+separate from their parent declaration.
+
+The current scope can be changed using three namespace directives. They manage
+a stack declarations where ``c:namespace`` resets the stack and changes a given
+scope.
+
+The ``c:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+
+The ``c:namespace-pop`` directive undoes the most recent
+``c:namespace-push`` directive.
+
+.. rst:directive:: .. c:namespace:: scope specification
+
+ Changes the current scope for the subsequent objects to the given scope, and
+ resets the namespace directive stack. Note that nested scopes can be
+ specified by separating with a dot, e.g.::
+
+ .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
+
+ All subsequent objects will be defined as if their name were declared with
+ the scope prepended. The subsequent cross-references will be searched for
+ starting in the current scope.
+
+ Using ``NULL`` or ``0`` as the scope will change to global scope.
+
+.. rst:directive:: .. c:namespace-push:: scope specification
+
+ Change the scope relatively to the current scope. For example, after::
+
+ .. c:namespace:: A.B
+
+ .. c:namespace-push:: C.D
+
+ the current scope will be ``A.B.C.D``.
+
+.. rst:directive:: .. c:namespace-pop::
+
+ Undo the previous ``c:namespace-push`` directive (*not* just pop a scope).
+ For example, after::
+
+ .. c:namespace:: A.B
+
+ .. c:namespace-push:: C.D
+
+ .. c:namespace-pop::
+
+ the current scope will be ``A.B`` (*not* ``A.B.C``).
+
+ If no previous ``c:namespace-push`` directive has been used, but only a
+ ``c:namespace`` directive, then the current scope will be reset to global
+ scope. That is, ``.. c:namespace:: A.B`` is equivalent to::
+
+ .. c:namespace:: NULL
+
+ .. c:namespace-push:: A.B
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`c-config`.
+
+
+.. _cpp-domain:
+
+The C++ Domain
+--------------
+
+The C++ domain (name **cpp**) supports documenting C++ projects.
+
+Directives for Declaring Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following directives are available. All declarations can start with a
+visibility statement (``public``, ``private`` or ``protected``).
+
+.. rst:directive:: .. cpp:class:: class specifier
+ .. cpp:struct:: class specifier
+
+ Describe a class/struct, possibly with specification of inheritance, e.g.,::
+
+ .. cpp:class:: MyClass : public MyBase, MyOtherBase
+
+ The difference between :rst:dir:`cpp:class` and :rst:dir:`cpp:struct` is
+ only cosmetic: the prefix rendered in the output, and the specifier shown
+ in the index.
+
+ The class can be directly declared inside a nested scope, e.g.,::
+
+ .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
+
+ A class template can be declared::
+
+ .. cpp:class:: template<typename T, std::size_t N> std::array
+
+ or with a line break::
+
+ .. cpp:class:: template<typename T, std::size_t N> \
+ std::array
+
+ Full and partial template specialisations can be declared::
+
+ .. cpp:class:: template<> \
+ std::array<bool, 256>
+
+ .. cpp:class:: template<typename T> \
+ std::array<T, 42>
+
+ .. versionadded:: 2.0
+ The :rst:dir:`cpp:struct` directive.
+
+.. rst:directive:: .. cpp:function:: (member) function prototype
+
+ Describe a function or member function, e.g.,::
+
+ .. cpp:function:: bool myMethod(int arg1, std::string arg2)
+
+ A function with parameters and types.
+
+ .. cpp:function:: bool myMethod(int, double)
+
+ A function with unnamed parameters.
+
+ .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
+
+ An overload for the indexing operator.
+
+ .. cpp:function:: operator bool() const
+
+ A casting operator.
+
+ .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
+
+ A constexpr function.
+
+ .. cpp:function:: MyClass::MyClass(const MyClass&) = default
+
+ A copy constructor with default implementation.
+
+ Function templates can also be described::
+
+ .. cpp:function:: template<typename U> \
+ void print(U &&u)
+
+ and function template specialisations::
+
+ .. cpp:function:: template<> \
+ void print(int i)
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`cpp_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. cpp:member:: (member) variable declaration
+ .. cpp:var:: (member) variable declaration
+
+ Describe a variable or member variable, e.g.,::
+
+ .. cpp:member:: std::string MyClass::myMember
+
+ .. cpp:var:: std::string MyClass::myOtherMember[N][M]
+
+ .. cpp:member:: int a = 42
+
+ Variable templates can also be described::
+
+ .. cpp:member:: template<class T> \
+ constexpr T pi = T(3.1415926535897932385)
+
+.. rst:directive:: .. cpp:type:: typedef declaration
+ .. cpp:type:: name
+ .. cpp:type:: type alias declaration
+
+ Describe a type as in a typedef declaration, a type alias declaration, or
+ simply the name of a type with unspecified type, e.g.,::
+
+ .. cpp:type:: std::vector<int> MyList
+
+ A typedef-like declaration of a type.
+
+ .. cpp:type:: MyContainer::const_iterator
+
+ Declaration of a type alias with unspecified type.
+
+ .. cpp:type:: MyType = std::unordered_map<int, std::string>
+
+ Declaration of a type alias.
+
+ A type alias can also be templated::
+
+ .. cpp:type:: template<typename T> \
+ MyContainer = std::vector<T>
+
+ The example are rendered as follows.
+
+ .. cpp:type:: std::vector<int> MyList
+ :no-contents-entry:
+ :no-index-entry:
+
+ A typedef-like declaration of a type.
+
+ .. cpp:type:: MyContainer::const_iterator
+ :no-contents-entry:
+ :no-index-entry:
+
+ Declaration of a type alias with unspecified type.
+
+ .. cpp:type:: MyType = std::unordered_map<int, std::string>
+ :no-contents-entry:
+ :no-index-entry:
+
+ Declaration of a type alias.
+
+ .. cpp:type:: template<typename T> \
+ MyContainer = std::vector<T>
+ :no-contents-entry:
+ :no-index-entry:
+
+.. rst:directive:: .. cpp:enum:: unscoped enum declaration
+ .. cpp:enum-struct:: scoped enum declaration
+ .. cpp:enum-class:: scoped enum declaration
+
+ Describe a (scoped) enum, possibly with the underlying type specified. Any
+ enumerators declared inside an unscoped enum will be declared both in the
+ enum scope and in the parent scope. Examples::
+
+ .. cpp:enum:: MyEnum
+
+ An unscoped enum.
+
+ .. cpp:enum:: MySpecificEnum : long
+
+ An unscoped enum with specified underlying type.
+
+ .. cpp:enum-class:: MyScopedEnum
+
+ A scoped enum.
+
+ .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
+
+ A scoped enum with non-default visibility, and with a specified
+ underlying type.
+
+.. rst:directive:: .. cpp:enumerator:: name
+ .. cpp:enumerator:: name = constant
+
+ Describe an enumerator, optionally with its value defined, e.g.,::
+
+ .. cpp:enumerator:: MyEnum::myEnumerator
+
+ .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
+
+.. rst:directive:: .. cpp:union:: name
+
+ Describe a union.
+
+ .. versionadded:: 1.8
+
+.. rst:directive:: .. cpp:concept:: template-parameter-list name
+
+ .. warning:: The support for concepts is experimental. It is based on the
+ current draft standard and the Concepts Technical Specification.
+ The features may change as they evolve.
+
+ Describe a concept. It must have exactly 1 template parameter list. The name
+ may be a nested name. Example::
+
+ .. cpp:concept:: template<typename It> std::Iterator
+
+ Proxy to an element of a notional sequence that can be compared,
+ indirected, or incremented.
+
+ **Notation**
+
+ .. cpp:var:: It r
+
+ An lvalue.
+
+ **Valid Expressions**
+
+ - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+ - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
+ :cpp:expr:`r` is incrementable.
+
+ This will render as follows:
+
+ .. cpp:concept:: template<typename It> std::Iterator
+
+ Proxy to an element of a notional sequence that can be compared,
+ indirected, or incremented.
+
+ **Notation**
+
+ .. cpp:var:: It r
+
+ An lvalue.
+
+ **Valid Expressions**
+
+ - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+ - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r`
+ is incrementable.
+
+ .. versionadded:: 1.5
+
+
+Options
+^^^^^^^
+
+Some directives support options:
+
+- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`.
+- ``:tparam-line-spec:``, for templated declarations.
+ If specified, each template parameter will be rendered on a separate line.
+
+ .. versionadded:: 1.6
+
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C++ supports anonymous namespaces, classes, enums, and unions.
+For the sake of documentation they must be given some name that starts with
+``@``, e.g., ``@42`` or ``@data``.
+These names can also be used in cross-references and (type) expressions,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
+link).
+
+Example::
+
+ .. cpp:class:: Data
+
+ .. cpp:union:: @data
+
+ .. cpp:var:: int a
+
+ .. cpp:var:: double b
+
+ Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+This will be rendered as:
+
+.. cpp:class:: Data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. cpp:union:: @data
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. cpp:var:: int a
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. cpp:var:: double b
+ :no-contents-entry:
+ :no-index-entry:
+
+Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+.. versionadded:: 1.8
+
+
+Aliasing Declarations
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes it may be helpful list declarations elsewhere than their main
+documentation, e.g., when creating a synopsis of a class interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. cpp:alias:: name or function signature
+
+ Insert one or more alias declarations. Each entity can be specified
+ as they can in the :rst:role:`cpp:any` role.
+ If the name of a function is given (as opposed to the complete signature),
+ then all overloads of the function will be listed.
+
+ For example::
+
+ .. cpp:alias:: Data::a
+ overload_example::C::f
+
+ becomes
+
+ .. cpp:alias:: Data::a
+ overload_example::C::f
+
+ whereas::
+
+ .. cpp:alias:: void overload_example::C::f(double d) const
+ void overload_example::C::f(double d)
+
+ becomes
+
+ .. cpp:alias:: void overload_example::C::f(double d) const
+ void overload_example::C::f(double d)
+
+ .. versionadded:: 2.0
+
+
+ .. rubric:: Options
+
+ .. rst:directive:option:: maxdepth: int
+
+ Insert nested declarations as well, up to the total depth given.
+ Use 0 for infinite depth and 1 for just the mentioned declaration.
+ Defaults to 1.
+
+ .. versionadded:: 3.5
+
+ .. rst:directive:option:: noroot
+
+ Skip the mentioned declarations and only render nested declarations.
+ Requires ``maxdepth`` either 0 or at least 2.
+
+ .. versionadded:: 3.5
+
+
+Constrained Templates
+~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: The support for concepts is experimental. It is based on the
+ current draft standard and the Concepts Technical Specification.
+ The features may change as they evolve.
+
+.. note:: Sphinx does not currently support ``requires`` clauses.
+
+Placeholders
+^^^^^^^^^^^^
+
+Declarations may use the name of a concept to introduce constrained template
+parameters, or the keyword ``auto`` to introduce unconstrained template
+parameters::
+
+ .. cpp:function:: void f(auto &&arg)
+
+ A function template with a single unconstrained template parameter.
+
+ .. cpp:function:: void f(std::Iterator it)
+
+ A function template with a single template parameter, constrained by the
+ Iterator concept.
+
+Template Introductions
+^^^^^^^^^^^^^^^^^^^^^^
+
+Simple constrained function or class templates can be declared with a `template
+introduction` instead of a template parameter list::
+
+ .. cpp:function:: std::Iterator{It} void advance(It &it)
+
+ A function template with a template parameter constrained to be an
+ Iterator.
+
+ .. cpp:class:: std::LessThanComparable{T} MySortedContainer
+
+ A class template with a template parameter constrained to be
+ LessThanComparable.
+
+They are rendered as follows.
+
+.. cpp:function:: std::Iterator{It} void advance(It &it)
+ :no-contents-entry:
+ :no-index-entry:
+
+ A function template with a template parameter constrained to be an Iterator.
+
+.. cpp:class:: std::LessThanComparable{T} MySortedContainer
+ :no-contents-entry:
+ :no-index-entry:
+
+ A class template with a template parameter constrained to be
+ LessThanComparable.
+
+Note however that no checking is performed with respect to parameter
+compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
+even though it would not be valid C++.
+
+Inline Expressions and Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: cpp:expr
+ cpp:texpr
+
+ Insert a C++ expression or type either as inline code (``cpp:expr``)
+ or inline text (``cpp:texpr``). For example::
+
+ .. cpp:var:: int a = 42
+
+ .. cpp:function:: int f(int i)
+
+ An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
+
+ A type: :cpp:expr:`const MySortedContainer<int>&`
+ (or as text :cpp:texpr:`const MySortedContainer<int>&`).
+
+ will be rendered as follows:
+
+ .. cpp:var:: int a = 42
+ :no-contents-entry:
+ :no-index-entry:
+
+ .. cpp:function:: int f(int i)
+ :no-contents-entry:
+ :no-index-entry:
+
+ An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
+
+ A type: :cpp:expr:`const MySortedContainer<int>&`
+ (or as text :cpp:texpr:`const MySortedContainer<int>&`).
+
+ .. versionadded:: 1.7
+ The :rst:role:`cpp:expr` role.
+
+ .. versionadded:: 1.8
+ The :rst:role:`cpp:texpr` role.
+
+Namespacing
+~~~~~~~~~~~
+
+Declarations in the C++ domain are as default placed in global scope. The
+current scope can be changed using three namespace directives. They manage a
+stack declarations where ``cpp:namespace`` resets the stack and changes a given
+scope.
+
+The ``cpp:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+
+The ``cpp:namespace-pop`` directive undoes the most recent
+``cpp:namespace-push`` directive.
+
+.. rst:directive:: .. cpp:namespace:: scope specification
+
+ Changes the current scope for the subsequent objects to the given scope, and
+ resets the namespace directive stack. Note that the namespace does not need
+ to correspond to C++ namespaces, but can end in names of classes, e.g.,::
+
+ .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
+
+ All subsequent objects will be defined as if their name were declared with
+ the scope prepended. The subsequent cross-references will be searched for
+ starting in the current scope.
+
+ Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global
+ scope.
+
+ A namespace declaration can also be templated, e.g.,::
+
+ .. cpp:class:: template<typename T> \
+ std::vector
+
+ .. cpp:namespace:: template<typename T> std::vector
+
+ .. cpp:function:: std::size_t size() const
+
+ declares ``size`` as a member function of the class template
+ ``std::vector``. Equivalently this could have been declared using::
+
+ .. cpp:class:: template<typename T> \
+ std::vector
+
+ .. cpp:function:: std::size_t size() const
+
+ or::
+
+ .. cpp:class:: template<typename T> \
+ std::vector
+
+.. rst:directive:: .. cpp:namespace-push:: scope specification
+
+ Change the scope relatively to the current scope. For example, after::
+
+ .. cpp:namespace:: A::B
+
+ .. cpp:namespace-push:: C::D
+
+ the current scope will be ``A::B::C::D``.
+
+ .. versionadded:: 1.4
+
+.. rst:directive:: .. cpp:namespace-pop::
+
+ Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope).
+ For example, after::
+
+ .. cpp:namespace:: A::B
+
+ .. cpp:namespace-push:: C::D
+
+ .. cpp:namespace-pop::
+
+ the current scope will be ``A::B`` (*not* ``A::B::C``).
+
+ If no previous ``cpp:namespace-push`` directive has been used, but only a
+ ``cpp:namespace`` directive, then the current scope will be reset to global
+ scope. That is, ``.. cpp:namespace:: A::B`` is equivalent to::
+
+ .. cpp:namespace:: nullptr
+
+ .. cpp:namespace-push:: A::B
+
+ .. versionadded:: 1.4
+
+Info field lists
+~~~~~~~~~~~~~~~~~
+
+All the C++ directives for declaring entities support the following
+info fields (see also :ref:`info-field-lists`):
+
+* ``tparam``: Description of a template parameter.
+
+The :rst:dir:`cpp:function` directive additionally supports the
+following fields:
+
+* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter.
+* ``returns``, ``return``: Description of a return value.
+* ``retval``, ``retvals``: An alternative to ``returns`` for describing
+ the result of the function.
+* `throws`, `throw`, `exception`: Description of a possibly thrown exception.
+
+.. versionadded:: 4.3
+ The ``retval`` field type.
+
+.. _cpp-roles:
+
+Cross-referencing
+~~~~~~~~~~~~~~~~~
+
+These roles link to the given declaration types:
+
+.. rst:role:: cpp:any
+ cpp:class
+ cpp:struct
+ cpp:func
+ cpp:member
+ cpp:var
+ cpp:type
+ cpp:concept
+ cpp:enum
+ cpp:enumerator
+
+ Reference a C++ declaration by name (see below for details). The name must
+ be properly qualified relative to the position of the link.
+
+ .. versionadded:: 2.0
+ The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class`
+ role.
+
+.. admonition:: Note on References with Templates Parameters/Arguments
+
+ These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must
+ be taken when referencing a (partial) template specialization, e.g. if the
+ link looks like this: ``:cpp:class:`MyClass<int>```.
+ This is interpreted as a link to ``int`` with a title of ``MyClass``.
+ In this case, escape the opening angle bracket with a backslash,
+ like this: ``:cpp:class:`MyClass\<int>```.
+
+ When a custom title is not needed it may be useful to use the roles for
+ inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where
+ angle brackets do not need escaping.
+
+Declarations without template parameters and template arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For linking to non-templated declarations the name must be a nested name, e.g.,
+``f`` or ``MyClass::f``.
+
+
+Overloaded (member) functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a (member) function is referenced using just its name, the reference
+will point to an arbitrary matching overload.
+The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles use an alternative
+format, which simply is a complete function declaration.
+This will resolve to the exact matching overload.
+As example, consider the following class declaration:
+
+.. cpp:namespace-push:: overload_example
+.. cpp:class:: C
+
+ .. cpp:function:: void f(double d) const
+ .. cpp:function:: void f(double d)
+ .. cpp:function:: void f(int i)
+ .. cpp:function:: void f()
+
+References using the :rst:role:`cpp:func` role:
+
+- Arbitrary overload: ``C::f``, :cpp:func:`C::f`
+- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()`
+- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
+- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
+- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
+- Specific overload: ``void C::f(double) const``,
+ :cpp:func:`void C::f(double) const`
+
+Note that the :confval:`add_function_parentheses` configuration variable
+does not influence specific overload references.
+
+.. cpp:namespace-pop::
+
+
+Templated declarations
+^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declarations.
+
+.. cpp:class:: Wrapper
+
+ .. cpp:class:: template<typename TOuter> \
+ Outer
+
+ .. cpp:class:: template<typename TInner> \
+ Inner
+
+In general the reference must include the template parameter declarations,
+and template arguments for the prefix of qualified names. For example:
+
+- ``template\<typename TOuter> Wrapper::Outer``
+ (:cpp:class:`template\<typename TOuter> Wrapper::Outer`)
+- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
+ (:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`)
+
+Currently the lookup only succeed if the template parameter identifiers are
+equal strings. That is, ``template\<typename UOuter> Wrapper::Outer`` will not
+work.
+
+As a shorthand notation, if a template parameter list is omitted,
+then the lookup will assume either a primary template or a non-template,
+but not a partial template specialisation.
+This means the following references work as well:
+
+- ``Wrapper::Outer``
+ (:cpp:class:`Wrapper::Outer`)
+- ``Wrapper::Outer::Inner``
+ (:cpp:class:`Wrapper::Outer::Inner`)
+- ``template\<typename TInner> Wrapper::Outer::Inner``
+ (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
+
+(Full) Template Specialisations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declarations.
+
+.. cpp:class:: template<typename TOuter> \
+ Outer
+
+ .. cpp:class:: template<typename TInner> \
+ Inner
+
+.. cpp:class:: template<> \
+ Outer<int>
+
+ .. cpp:class:: template<typename TInner> \
+ Inner
+
+ .. cpp:class:: template<> \
+ Inner<bool>
+
+In general the reference must include a template parameter list for each
+template argument list. The full specialisation above can therefore be
+referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<>
+Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>``
+(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`). As a
+shorthand the empty template parameter list can be omitted, e.g.,
+``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>``
+(:cpp:class:`Outer\<int>::Inner\<bool>`).
+
+Partial Template Specialisations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declaration.
+
+.. cpp:class:: template<typename T> \
+ Outer<T*>
+
+References to partial specialisations must always include the template
+parameter lists, e.g., ``template\<typename T> Outer\<T*>``
+(:cpp:class:`template\<typename T> Outer\<T*>`). Currently the lookup only
+succeed if the template parameter identifiers are equal strings.
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`cpp-config`.
+
+.. _domains-std:
+
+The Standard Domain
+-------------------
+
+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:: .. 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.
+
+
+The JavaScript Domain
+---------------------
+
+The JavaScript domain (name **js**) provides the following directives:
+
+.. rst:directive:: .. js:module:: name
+
+ This directive sets the module name for object declarations that follow
+ after. The module name is used in the global module index and in cross
+ references. This directive does not create an object heading like
+ :rst:dir:`py:class` would, for example.
+
+ By default, this directive will create a linkable entity and will cause an
+ entry in the global module index, unless the ``no-index`` option is
+ specified. If this option is specified, the directive will only update the
+ current module name.
+
+ .. versionadded:: 1.6
+ .. versionchanged:: 5.2
+
+ Module directives support body content.
+
+.. rst:directive:: .. js:function:: name(signature)
+
+ Describes a JavaScript function or method. If you want to describe
+ arguments as optional use square brackets as :ref:`documented <signatures>`
+ for Python signatures.
+
+ You can use fields to give more details about arguments and their expected
+ types, errors which may be thrown by the function, and the value being
+ returned::
+
+ .. js:function:: $.getJSON(href, callback[, errback])
+
+ :param string href: An URI to the location of the resource.
+ :param callback: Gets called with the object.
+ :param errback:
+ Gets called in case the request fails. And a lot of other
+ text so we need multiple lines.
+ :throws SomeError: For whatever reason in that case.
+ :returns: Something.
+
+ This is rendered as:
+
+ .. js:function:: $.getJSON(href, callback[, errback])
+ :no-index:
+
+ :param string href: An URI to the location of the resource.
+ :param callback: Gets called with the object.
+ :param errback:
+ Gets called in case the request fails. And a lot of other
+ text so we need multiple lines.
+ :throws SomeError: For whatever reason in that case.
+ :returns: Something.
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`javascript_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. js:method:: name(signature)
+
+ This directive is an alias for :rst:dir:`js:function`, however it describes
+ a function that is implemented as a method on a class object.
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`javascript_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. js:class:: name
+
+ Describes a constructor that creates an object. This is basically like a
+ function but will show up with a `class` prefix::
+
+ .. js:class:: MyAnimal(name[, age])
+
+ :param string name: The name of the animal
+ :param number age: an optional age for the animal
+
+ This is rendered as:
+
+ .. js:class:: MyAnimal(name[, age])
+ :no-index:
+
+ :param string name: The name of the animal
+ :param number age: an optional age for the animal
+
+ .. rst:directive:option:: single-line-parameter-list
+ :type: no value
+
+ Ensures that the function's parameters will be emitted on a single logical
+ line, overriding :confval:`javascript_maximum_signature_line_length` and
+ :confval:`maximum_signature_line_length`.
+
+ .. versionadded:: 7.1
+
+.. rst:directive:: .. js:data:: name
+
+ Describes a global variable or constant.
+
+.. rst:directive:: .. js:attribute:: object.name
+
+ Describes the attribute *name* of *object*.
+
+.. _js-roles:
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: js:mod
+ js:func
+ js:meth
+ js:class
+ js:data
+ js:attr
+
+
+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
+
+.. _math-domain:
+
+The Math Domain
+---------------
+
+The math domain (name **math**) provides the following roles:
+
+.. rst:role:: math:numref
+
+ Role for cross-referencing equations defined by :rst:dir:`math` directive
+ via their label. Example::
+
+ .. math:: e^{i\pi} + 1 = 0
+ :label: euler
+
+ Euler's identity, equation :math:numref:`euler`, was elected one of the
+ most beautiful mathematical formulas.
+
+ .. versionadded:: 1.8
+
+More domains
+------------
+
+The sphinx-contrib_ repository contains more domains available as extensions;
+currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_
+domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_,
+Jinja_, Operation_, and Scala_.
+
+.. _sphinx-contrib: https://github.com/sphinx-contrib
+
+.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/
+.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/
+.. _CoffeeScript: https://pypi.org/project/sphinxcontrib-coffee/
+.. _Common Lisp: https://pypi.org/project/sphinxcontrib-cldomain/
+.. _dqn: https://pypi.org/project/sphinxcontrib-dqndomain/
+.. _Erlang: https://pypi.org/project/sphinxcontrib-erlangdomain/
+.. _Go: https://pypi.org/project/sphinxcontrib-golangdomain/
+.. _HTTP: https://pypi.org/project/sphinxcontrib-httpdomain/
+.. _Jinja: https://pypi.org/project/sphinxcontrib-jinjadomain/
+.. _Lasso: https://pypi.org/project/sphinxcontrib-lassodomain/
+.. _MATLAB: https://pypi.org/project/sphinxcontrib-matlabdomain/
+.. _Operation: https://pypi.org/project/sphinxcontrib-operationdomain/
+.. _PHP: https://pypi.org/project/sphinxcontrib-phpdomain/
+.. _Ruby: https://github.com/sphinx-contrib/rubydomain
+.. _Scala: https://pypi.org/project/sphinxcontrib-scaladomain/
diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst
new file mode 100644
index 0000000..5fc897d
--- /dev/null
+++ b/doc/usage/restructuredtext/field-lists.rst
@@ -0,0 +1,78 @@
+.. highlight:: rst
+
+===========
+Field Lists
+===========
+
+:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of
+fields marked up like this::
+
+ :fieldname: Field content
+
+Sphinx extends standard docutils behavior for field lists and adds some extra
+functionality that is covered in this section.
+
+.. note::
+
+ The values of field lists will be parsed as
+ strings. You cannot use Python collections such as lists or dictionaries.
+
+
+.. _metadata:
+
+File-wide metadata
+------------------
+
+A field list near the top of a file is normally parsed by docutils as the
+*docinfo* and shown on the page. However, in Sphinx, a field list preceding
+any other markup is moved from the *docinfo* to the Sphinx environment as
+document metadata, and is not displayed in the output.
+
+.. note::
+
+ A field list appearing after the document title *will* be part of the
+ *docinfo* as normal and will be displayed in the output.
+
+
+Special metadata fields
+-----------------------
+
+Sphinx provides custom behavior for bibliographic fields compared to docutils.
+
+At the moment, these metadata fields are recognized:
+
+``tocdepth``
+ The maximum depth for a table of contents of this file. ::
+
+ :tocdepth: 2
+
+ .. note::
+
+ This metadata effects to the depth of local toctree. But it does not
+ effect to the depth of *global* toctree. So this would not be change
+ the sidebar of some themes which uses global one.
+
+ .. versionadded:: 0.4
+
+``nocomments``
+ If set, the web application won't display a comment form for a page
+ generated from this source file. ::
+
+ :nocomments:
+
+``orphan``
+ If set, warnings about this file not being included in any toctree will be
+ suppressed. ::
+
+ :orphan:
+
+ .. versionadded:: 1.0
+
+``nosearch``
+ If set, full text search for this file is disabled. ::
+
+ :nosearch:
+
+ .. note:: object search is still available even if `nosearch` option is set.
+
+ .. versionadded:: 3.0
diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst
new file mode 100644
index 0000000..87b6ed6
--- /dev/null
+++ b/doc/usage/restructuredtext/index.rst
@@ -0,0 +1,24 @@
+.. _rst-index:
+
+================
+reStructuredText
+================
+
+reStructuredText (reST) is the default plaintext markup language used by both
+Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while
+Sphinx extends this to support additional functionality.
+
+The below guides go through the most important aspects of reST. For the
+authoritative reStructuredText reference, refer to the `docutils
+documentation`__.
+
+__ https://docutils.sourceforge.io/rst.html
+
+.. toctree::
+ :maxdepth: 2
+
+ basics
+ roles
+ directives
+ field-lists
+ domains
diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst
new file mode 100644
index 0000000..e468de9
--- /dev/null
+++ b/doc/usage/restructuredtext/roles.rst
@@ -0,0 +1,536 @@
+.. highlight:: rst
+
+=====
+Roles
+=====
+
+Sphinx uses interpreted text roles to insert semantic markup into documents.
+They are written as ``:rolename:`content```.
+
+.. note::
+
+ The default role (```content```) has no special meaning by default. You are
+ free to use it for anything you like, e.g. variable names; use the
+ :confval:`default_role` config value to set it to a known role -- the
+ :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find
+ Python objects are very useful for this.
+
+See :doc:`/usage/restructuredtext/domains` for roles added by domains.
+
+
+.. _xref-syntax:
+
+Cross-referencing syntax
+------------------------
+
+Cross-references are generated by many semantic interpreted text roles.
+Basically, you only need to write ``:role:`target```, and a link will be
+created to the item named *target* of the type indicated by *role*. The link's
+text will be the same as *target*.
+
+There are some additional facilities, however, that make cross-referencing
+roles more versatile:
+
+* You may supply an explicit title and reference target, like in reST direct
+ hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
+ text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+ component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will
+ refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This
+ does not work with all cross-reference roles, but is domain specific.
+
+ In HTML output, the link's ``title`` attribute (that is e.g. shown as a
+ tool-tip on mouse-hover) will always be the full target name.
+
+
+.. _any-role:
+
+Cross-referencing anything
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. rst:role:: any
+
+ .. versionadded:: 1.3
+
+ This convenience role tries to do its best to find a valid target for its
+ reference text.
+
+ * First, it tries standard cross-reference targets that would be referenced
+ by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
+
+ Custom objects added to the standard domain by extensions (see
+ :meth:`.Sphinx.add_object_type`) are also searched.
+
+ * Then, it looks for objects (targets) in all loaded domains. It is up to
+ the domains how specific a match must be. For example, in the Python
+ domain a reference of ``:any:`Builder``` would match the
+ ``sphinx.builders.Builder`` class.
+
+ If none or multiple targets are found, a warning will be emitted. In the
+ case of multiple targets, you can change "any" to a specific role.
+
+ This role is a good candidate for setting :confval:`default_role`. If you
+ do, you can write cross-references without a lot of markup overhead. For
+ example, in this Python function documentation::
+
+ .. function:: install()
+
+ This function installs a `handler` for every signal known by the
+ `signal` module. See the section `about-signals` for more information.
+
+ there could be references to a glossary term (usually ``:term:`handler```), a
+ Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a
+ section (usually ``:ref:`about-signals```).
+
+ The :rst:role:`any` role also works together with the
+ :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
+ found, all object types of intersphinx inventories are also searched.
+
+Cross-referencing objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These roles are described with their respective domains:
+
+* :ref:`Python <python-roles>`
+* :ref:`C <c-roles>`
+* :ref:`C++ <cpp-roles>`
+* :ref:`JavaScript <js-roles>`
+* :ref:`ReST <rst-roles>`
+
+
+.. _ref-role:
+
+Cross-referencing arbitrary locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. rst:role:: ref
+
+ To support cross-referencing to arbitrary locations in any document, the
+ standard reST labels are used. For this to work label names must be unique
+ throughout the entire documentation. There are two ways in which you can
+ refer to labels:
+
+ * If you place a label directly before a section title, you can reference to
+ it with ``:ref:`label-name```. For example::
+
+ .. _my-reference-label:
+
+ Section to cross-reference
+ --------------------------
+
+ This is the text of the section.
+
+ It refers to the section itself, see :ref:`my-reference-label`.
+
+ The ``:ref:`` role would then generate a link to the section, with the
+ link title being "Section to cross-reference". This works just as well
+ when section and reference are in different source files.
+
+ Automatic labels also work with figures. For example::
+
+ .. _my-figure:
+
+ .. figure:: whatever
+
+ Figure caption
+
+ In this case, a reference ``:ref:`my-figure``` would insert a reference
+ to the figure with link text "Figure caption".
+
+ The same works for tables that are given an explicit caption using the
+ :dudir:`table` directive.
+
+ * Labels that aren't placed before a section title can still be referenced,
+ but you must give the link an explicit title, using this syntax:
+ ``:ref:`Link title <label-name>```.
+
+ .. note::
+
+ Reference labels must start with an underscore. When referencing a label,
+ the underscore must be omitted (see examples above).
+
+ Using :rst:role:`ref` is advised over standard reStructuredText links to
+ sections (like ```Section title`_``) because it works across files, when
+ section headings are changed, will raise warnings if incorrect, and works
+ for all builders that support cross-references.
+
+
+Cross-referencing documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.6
+
+There is also a way to directly link to documents:
+
+.. rst:role:: doc
+
+ Link to the specified document; the document name can be specified in
+ absolute or relative fashion. For example, if the reference
+ ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
+ refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or
+ ``:doc:`../people```, the link refers to ``people``.
+
+ If no explicit link text is given (like usual: ``:doc:`Monty Python members
+ </people>```), the link caption will be the title of the given document.
+
+
+Referencing downloadable files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.6
+
+.. rst:role:: download
+
+ This role lets you link to files within your source tree that are not reST
+ documents that can be viewed, but files that can be downloaded.
+
+ When you use this role, the referenced file is automatically marked for
+ inclusion in the output when building (obviously, for HTML output only).
+ All downloadable files are put into a ``_downloads/<unique hash>/``
+ subdirectory of the output directory; duplicate filenames are handled.
+
+ An example::
+
+ See :download:`this example script <../example.py>`.
+
+ The given filename is usually relative to the directory the current source
+ file is contained in, but if it absolute (starting with ``/``), it is taken
+ as relative to the top source directory.
+
+ The ``example.py`` file will be copied to the output directory, and a
+ suitable link generated to it.
+
+ Not to show unavailable download links, you should wrap whole paragraphs that
+ have this role::
+
+ .. only:: builder_html
+
+ See :download:`this example script <../example.py>`.
+
+Cross-referencing figures by figure number
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.3
+
+.. versionchanged:: 1.5
+ `numref` role can also refer sections.
+ And `numref` allows `{name}` for the link text.
+
+.. rst:role:: numref
+
+ Link to the specified figures, tables, code-blocks and sections; the standard
+ reST labels are used. When you use this role, it will insert a reference to
+ the figure with link text by its figure number like "Fig. 1.1".
+
+ If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig.
+ %s) <my-figure>```), the link caption will serve as title of the reference.
+ As placeholders, `%s` and `{number}` get replaced by the figure
+ number and `{name}` by the figure caption.
+ If no explicit link text is given, the :confval:`numfig_format` setting is
+ used as fall-back default.
+
+ If :confval:`numfig` is ``False``, figures are not numbered,
+ so this role inserts not a reference but the label or the link text.
+
+Cross-referencing other items of interest
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. rst:role:: envvar
+
+ An environment variable. Index entries are generated. Also generates a link
+ to the matching :rst:dir:`envvar` directive, if it exists.
+
+.. rst:role:: token
+
+ The name of a grammar token (used to create links between
+ :rst:dir:`productionlist` directives).
+
+.. rst:role:: keyword
+
+ The name of a keyword in Python. This creates a link to a reference label
+ with that name, if it exists.
+
+.. rst:role:: option
+
+ A command-line option to an executable program. This generates a link to
+ a :rst:dir:`option` directive, if it exists.
+
+
+The following role creates a cross-reference to a term in a
+:ref:`glossary <glossary-directive>`:
+
+.. rst:role:: term
+
+ Reference to a term in a glossary. A glossary is created using the
+ ``glossary`` directive containing a definition list with terms and
+ definitions. It does not have to be in the same file as the ``term`` markup,
+ for example the Python docs have one global glossary in the ``glossary.rst``
+ file.
+
+ If you use a term that's not explained in a glossary, you'll get a warning
+ during build.
+
+Inline code highlighting
+------------------------
+
+.. rst:role:: code
+
+ An *inline* code example. When used directly, this role just displays the
+ text *without* syntax highlighting, as a literal.
+
+ .. code-block:: rst
+
+ By default, inline code such as :code:`1 + 2` just displays without
+ highlighting.
+
+ Displays: By default, inline code such as :code:`1 + 2` just displays without
+ highlighting.
+
+ Unlike the :rst:dir:`code-block` directive, this role does not respect the
+ default language set by the :rst:dir:`highlight` directive.
+
+ To enable syntax highlighting, you must first use the Docutils :dudir:`role`
+ directive to define a custom role associated with a specific language:
+
+ .. code-block:: rst
+
+ .. role:: python(code)
+ :language: python
+
+ In Python, :python:`1 + 2` is equal to :python:`3`.
+
+ To display a multi-line code example, use the :rst:dir:`code-block` directive
+ instead.
+
+Math
+----
+
+.. rst:role:: math
+
+ Role for inline math. Use like this::
+
+ Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+ Displays: Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+.. rst:role:: eq
+
+ Same as :rst:role:`math:numref`.
+
+
+Other semantic markup
+---------------------
+
+The following roles don't do anything special except formatting the text in a
+different style:
+
+.. rst:role:: abbr
+
+ An abbreviation. If the role content contains a parenthesized explanation,
+ it will be treated specially: it will be shown in a tool-tip in HTML, and
+ output only once in LaTeX.
+
+ For example: ``:abbr:`LIFO (last-in, first-out)``` displays
+ :abbr:`LIFO (last-in, first-out)`.
+
+ .. versionadded:: 0.6
+
+.. rst:role:: command
+
+ The name of an OS-level command, such as ``rm``.
+
+ For example: :command:`rm`
+
+.. rst:role:: dfn
+
+ Mark the defining instance of a term in the text. (No index entries are
+ generated.)
+
+ For example: :dfn:`binary mode`
+
+.. rst:role:: file
+
+ The name of a file or directory. Within the contents, you can use curly
+ braces to indicate a "variable" part, for example::
+
+ ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
+
+ Displays: ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
+
+ In the built documentation, the ``x`` will be displayed differently to
+ indicate that it is to be replaced by the Python minor version.
+
+.. rst:role:: guilabel
+
+ Labels presented as part of an interactive user interface should be marked
+ using ``guilabel``. This includes labels from text-based interfaces such as
+ those created using :mod:`curses` or other text-based libraries. Any label
+ used in the interface should be marked with this role, including button
+ labels, window titles, field names, menu and menu selection names, and even
+ values in selection lists.
+
+ .. versionchanged:: 1.0
+ An accelerator key for the GUI label can be included using an ampersand;
+ this will be stripped and displayed underlined in the output (for example:
+ ``:guilabel:`&Cancel``` displays :guilabel:`&Cancel`). To include a literal
+ ampersand, double it.
+
+.. rst:role:: kbd
+
+ Mark a sequence of keystrokes. What form the key sequence takes may depend
+ on platform- or application-specific conventions. When there are no
+ relevant conventions, the names of modifier keys should be spelled out, to
+ improve accessibility for new users and non-native speakers. For example,
+ an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+ reference to a specific application or platform, the same sequence should be
+ marked as ``:kbd:`Control-x Control-f```, displaying :kbd:`C-x C-f` and
+ :kbd:`Control-x Control-f` respectively.
+
+.. rst:role:: mailheader
+
+ The name of an RFC 822-style mail header. This markup does not imply that
+ the header is being used in an email message, but can be used to refer to
+ any header of the same "style." This is also used for headers defined by
+ the various MIME specifications. The header name should be entered in the
+ same way it would normally be found in practice, with the camel-casing
+ conventions being preferred where there is more than one common usage. For
+ example: ``:mailheader:`Content-Type``` displays :mailheader:`Content-Type`.
+
+.. rst:role:: makevar
+
+ The name of a :command:`make` variable.
+
+ For example: :makevar:`help`
+
+.. rst:role:: manpage
+
+ A reference to a Unix manual page including the section, e.g.
+ ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an
+ external site rendering the manpage if :confval:`manpages_url` is defined.
+
+.. rst:role:: menuselection
+
+ Menu selections should be marked using the ``menuselection`` role. This is
+ used to mark a complete sequence of menu selections, including selecting
+ submenus and choosing a specific operation, or any subsequence of such a
+ sequence. The names of individual selections should be separated by
+ ``-->``.
+
+ For example, to mark the selection "Start > Programs", use this markup::
+
+ :menuselection:`Start --> Programs`
+
+ Displays: :menuselection:`Start --> Programs`
+
+ When including a selection that includes some trailing indicator, such as
+ the ellipsis some operating systems use to indicate that the command opens a
+ dialog, the indicator should be omitted from the selection name.
+
+ ``menuselection`` also supports ampersand accelerators just like
+ :rst:role:`guilabel`.
+
+.. rst:role:: mimetype
+
+ The name of a MIME type, or a component of a MIME type (the major or minor
+ portion, taken alone).
+
+ For example: :mimetype:`text/plain`
+
+.. rst:role:: newsgroup
+
+ The name of a Usenet newsgroup.
+
+ For example: :newsgroup:`comp.lang.python`
+
+.. todo:: Is this not part of the standard domain?
+
+.. rst:role:: program
+
+ The name of an executable program. This may differ from the file name for
+ the executable for some platforms. In particular, the ``.exe`` (or other)
+ extension should be omitted for Windows programs.
+
+ For example: :program:`curl`
+
+.. rst:role:: regexp
+
+ A regular expression. Quotes should not be included.
+
+ For example: :regexp:`([abc])+`
+
+.. rst:role:: samp
+
+ A piece of literal text, such as code. Within the contents, you can use
+ curly braces to indicate a "variable" part, as in :rst:role:`file`. For
+ example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be
+ emphasized: :samp:`print 1+{variable}`
+
+ If you don't need the "variable part" indication, use the standard
+ :rst:role:`code` role instead.
+
+ .. versionchanged:: 1.8
+ Allowed to escape curly braces with backslash
+
+There is also an :rst:role:`index` role to generate index entries.
+
+The following roles generate external links:
+
+.. rst:role:: pep
+
+ A reference to a Python Enhancement Proposal. This generates appropriate
+ index entries. The text "PEP *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified PEP. You can
+ link to a specific section by saying ``:pep:`number#anchor```.
+
+ For example: :pep:`8`
+
+.. rst:role:: rfc
+
+ A reference to an Internet Request for Comments. This generates appropriate
+ index entries. The text "RFC *number*\ " is generated; in the HTML output,
+ this text is a hyperlink to an online copy of the specified RFC. You can
+ link to a specific section by saying ``:rfc:`number#anchor```.
+
+ For example: :rfc:`2324`
+
+Note that there are no special roles for including hyperlinks as you can use
+the standard reST markup for that purpose.
+
+
+.. _default-substitutions:
+
+Substitutions
+-------------
+
+The documentation system provides three substitutions that are defined by
+default. They are set in the build configuration file.
+
+.. describe:: |release|
+
+ Replaced by the project release the documentation refers to. This is meant
+ to be the full version string including alpha/beta/release candidate tags,
+ e.g. ``2.5.2b3``. Set by :confval:`release`.
+
+.. describe:: |version|
+
+ Replaced by the project version the documentation refers to. This is meant to
+ consist only of the major and minor version parts, e.g. ``2.5``, even for
+ version 2.5.1. Set by :confval:`version`.
+
+.. describe:: |today|
+
+ Replaced by either today's date (the date on which the document is read), or
+ the date set in the build configuration file. Normally has the format
+ ``April 14, 2007``. Set by :confval:`today_fmt` and :confval:`today`.
+
+.. describe:: |translation progress|
+
+ Replaced by the translation progress of the document.
+ This substitution is intented for use by document translators
+ as a marker for the translation progress of the document.