diff options
Diffstat (limited to 'doc/usage/restructuredtext')
| -rw-r--r-- | doc/usage/restructuredtext/basics.rst | 631 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/directives.rst | 1311 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/domains.rst | 2303 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/field-lists.rst | 78 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/index.rst | 24 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/roles.rst | 536 |
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. |