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 | 1323 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/domains.rst | 278 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/field-lists.rst | 78 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/index.rst | 28 | ||||
| -rw-r--r-- | doc/usage/restructuredtext/roles.rst | 304 |
6 files changed, 2642 insertions, 0 deletions
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst new file mode 100644 index 0000000..7aab544 --- /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" (:dupage:`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..ff42524 --- /dev/null +++ b/doc/usage/restructuredtext/directives.rst @@ -0,0 +1,1323 @@ +.. 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/domains/index` 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:: .. versionremoved:: version + + Similar to :rst:dir:`versionadded`, but describes when the feature was removed. + An explanation may be provided to inform the reader what to use instead, + or why the feature was removed. + Example:: + + .. versionremoved:: 4.0 + The :func:`spam` function is more flexible, and should be used instead. + + .. versionadded:: 7.3 + +.. 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 <https://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/domains/index`. + +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 ``(latex or html) and 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..3d9bd49 --- /dev/null +++ b/doc/usage/restructuredtext/domains.rst @@ -0,0 +1,278 @@ +============== +MOVED: Domains +============== + +MOVED: Basic Markup +------------------- + +.. raw:: html + + <span id="basic-markup"> + <span id="basic-domain-markup"> + <span id="directive-default-domain"> + <span id="cross-referencing-syntax"> + +See :doc:`/usage/domains/index`. + + +MOVED: Python Domain +-------------------- + +.. raw:: html + + <span id="the-python-domain"> + <span id="python-domain"> + <span id="directive-py-module"> + <span id="directive-option-py-module-platform"> + <span id="directive-option-py-module-synopsis"> + <span id="directive-option-py-module-deprecated"> + <span id="directive-py-currentmodule"> + <span id="directive-py-function"> + <span id="directive-option-py-function-async"> + <span id="directive-option-py-function-canonical"> + <span id="directive-option-py-function-single-line-parameter-list"> + <span id="directive-option-py-function-single-line-type-parameter-list"> + <span id="directive-py-data"> + <span id="directive-option-py-data-type"> + <span id="directive-option-py-data-value"> + <span id="directive-option-py-data-canonical"> + <span id="directive-py-exception"> + <span id="index-0"> + <span id="directive-option-py-exception-final"> + <span id="directive-option-py-exception-single-line-parameter-list"> + <span id="directive-option-py-exception-single-line-type-parameter-list"> + <span id="directive-py-class"> + <span id="index-1"> + <span id="directive-option-py-class-canonical"> + <span id="directive-option-py-class-final"> + <span id="directive-option-py-class-single-line-parameter-list"> + <span id="directive-option-py-class-single-line-type-parameter-list"> + <span id="directive-py-attribute"> + <span id="directive-option-py-attribute-type"> + <span id="directive-option-py-attribute-value"> + <span id="directive-option-py-attribute-canonical"> + <span id="directive-py-property"> + <span id="directive-option-py-property-abstractmethod"> + <span id="directive-option-py-property-classmethod"> + <span id="directive-option-py-property-type"> + <span id="directive-py-method"> + <span id="directive-option-py-method-abstractmethod"> + <span id="directive-option-py-method-async"> + <span id="directive-option-py-method-canonical"> + <span id="directive-option-py-method-classmethod"> + <span id="directive-option-py-method-final"> + <span id="directive-option-py-method-single-line-parameter-list"> + <span id="directive-option-py-method-single-line-type-parameter-list"> + <span id="directive-option-py-method-staticmethod"> + <span id="directive-py-staticmethod"> + <span id="directive-py-classmethod"> + <span id="directive-py-decorator"> + <span id="directive-option-py-decorator-single-line-parameter-list"> + <span id="directive-option-py-decorator-single-line-type-parameter-list"> + <span id="directive-py-decoratormethod"> + <span id="python-signatures"> + <span id="signatures"> + <span id="index-2"> + <span id="index-3"> + <span id="info-field-lists"> + <span id="id1"> + <span id="cross-referencing-python-objects"> + <span id="python-roles"> + <span id="role-py-mod"> + <span id="role-py-func"> + <span id="role-py-data"> + <span id="role-py-const"> + <span id="role-py-class"> + <span id="role-py-meth"> + <span id="role-py-attr"> + <span id="role-py-exc"> + <span id="role-py-obj"> + +See :doc:`/usage/domains/python`. + + +MOVED: C Domain +--------------- + +.. raw:: html + + <span id="the-c-domain"> + <span id="c-domain"> + <span id="directive-c-member"> + <span id="directive-c-var"> + <span id="directive-c-function"> + <span id="directive-option-c-function-single-line-parameter-list"> + <span id="directive-c-macro"> + <span id="directive-option-c-macro-single-line-parameter-list"> + <span id="directive-c-struct"> + <span id="directive-c-union"> + <span id="directive-c-enum"> + <span id="directive-c-enumerator"> + <span id="directive-c-type"> + <span id="cross-referencing-c-constructs"> + <span id="c-roles"> + <span id="role-c-member"> + <span id="role-c-data"> + <span id="role-c-var"> + <span id="role-c-func"> + <span id="role-c-macro"> + <span id="role-c-struct"> + <span id="role-c-union"> + <span id="role-c-enum"> + <span id="role-c-enumerator"> + <span id="role-c-type"> + <span id="anonymous-entities"> + <span id="aliasing-declarations"> + <span id="directive-c-alias"> + <span id="directive-option-c-alias-maxdepth"> + <span id="directive-option-c-alias-noroot"> + <span id="inline-expressions-and-types"> + <span id="role-c-expr"> + <span id="role-c-texpr"> + <span id="namespacing"> + <span id="directive-c-namespace"> + <span id="directive-c-namespace-push"> + <span id="directive-c-namespace-pop"> + <span id="configuration-variables"> + +See :doc:`/usage/domains/c`. + + +MOVED: C++ Domain +----------------- + +.. raw:: html + + <span id="cpp-domain"> + <span id="id2"> + <span id="directives-for-declaring-entities"> + <span id="directive-cpp-class"> + <span id="directive-cpp-struct"> + <span id="directive-cpp-function"> + <span id="directive-option-cpp-function-single-line-parameter-list"> + <span id="directive-cpp-member"> + <span id="directive-cpp-var"> + <span id="directive-cpp-type"> + <span id="directive-cpp-enum"> + <span id="directive-cpp-enum-struct"> + <span id="directive-cpp-enum-class"> + <span id="directive-cpp-enumerator"> + <span id="directive-cpp-union"> + <span id="directive-cpp-concept"> + <span id="options"> + <span id="id3"> + <span id="id4"> + <span id="directive-cpp-alias"> + <span id="directive-option-cpp-alias-maxdepth"> + <span id="directive-option-cpp-alias-noroot"> + <span id="constrained-templates"> + <span id="placeholders"> + <span id="template-introductions"> + <span id="id5"> + <span id="role-cpp-expr"> + <span id="role-cpp-texpr"> + <span id="id6"> + <span id="directive-cpp-namespace"> + <span id="directive-cpp-namespace-push"> + <span id="directive-cpp-namespace-pop"> + <span id="id7"> + <span id="cross-referencing"> + <span id="cpp-roles"> + <span id="role-cpp-any"> + <span id="role-cpp-class"> + <span id="role-cpp-struct"> + <span id="role-cpp-func"> + <span id="role-cpp-member"> + <span id="role-cpp-var"> + <span id="role-cpp-type"> + <span id="role-cpp-concept"> + <span id="role-cpp-enum"> + <span id="role-cpp-enumerator"> + <span id="declarations-without-template-parameters-and-template-arguments"> + <span id="overloaded-member-functions"> + <span id="templated-declarations"> + <span id="full-template-specialisations"> + <span id="partial-template-specialisations"> + <span id="id8"> + +See :doc:`/usage/domains/cpp`. + + +MOVED: Standard Domain +---------------------- + +.. raw:: html + + <span id="the-standard-domain"> + <span id="domains-std"> + <span id="directive-option"> + <span id="directive-envvar"> + <span id="directive-program"> + <span id="directive-describe"> + <span id="directive-object"> + +See :doc:`/usage/domains/standard`. + + +MOVED: JavaScript Domain +------------------------ + +.. raw:: html + + <span id="the-javascript-domain"> + <span id="directive-js-module"> + <span id="directive-js-function"> + <span id="directive-option-js-function-single-line-parameter-list"> + <span id="directive-js-method"> + <span id="directive-option-js-method-single-line-parameter-list"> + <span id="directive-js-class"> + <span id="directive-option-js-class-single-line-parameter-list"> + <span id="directive-js-data"> + <span id="directive-js-attribute"> + <span id="js-roles"> + <span id="role-js-mod"> + <span id="role-js-func"> + <span id="role-js-meth"> + <span id="role-js-class"> + <span id="role-js-data"> + <span id="role-js-attr"> + +See :doc:`/usage/domains/javascript`. + + +MOVED: reStructuredText Domain +------------------------------ + +.. raw:: html + + <span id="the-restructuredtext-domain"> + <span id="directive-rst-directive"> + <span id="directive-rst-directive-option"> + <span id="directive-option-rst-directive-option-type"> + <span id="directive-rst-role"> + <span id="rst-roles"> + <span id="role-rst-dir"> + <span id="role-rst-role"> + +See :doc:`/usage/domains/restructuredtext`. + + +MOVED: Math Domain +------------------ + +.. raw:: html + + <span id="the-math-domain"> + <span id="math-domain"> + <span id="role-math-numref"> + +See :doc:`/usage/domains/mathematics`. + +MOVED: More domains +------------------- + +.. raw:: html + + <span id="more-domains"> + +See :doc:`/usage/domains/index`. diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst new file mode 100644 index 0000000..62dad5c --- /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..0fe311e --- /dev/null +++ b/doc/usage/restructuredtext/index.rst @@ -0,0 +1,28 @@ +.. _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 + +.. toctree:: + :hidden: + + domains diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst new file mode 100644 index 0000000..b21a2b7 --- /dev/null +++ b/doc/usage/restructuredtext/roles.rst @@ -0,0 +1,304 @@ +.. 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/domains/index` for roles added by domains. + + +Cross-referencing syntax +------------------------ + +See :doc:`/usage/referencing/`. + +Cross-reference roles include: + +* :rst:role:`any` +* :rst:role:`doc` +* :rst:role:`download` +* :rst:role:`envvar` +* :rst:role:`keyword` +* :rst:role:`numref` +* :rst:role:`option` (and the deprecated :rst:role:`!cmdoption`) +* :rst:role:`ref` +* :rst:role:`term` +* :rst:role:`token` + + +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. + + .. versionchanged:: 7.3 + Allow specifying a target with ``<>``, like hyperlinks. + For example, ``:manpage:`blah <ls(1)>``` displays :manpage:`blah <ls(1)>`. + +.. 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 double backslash. For example, in + ``:samp:`print(f"answer=\\{1+{variable}*2\\}")```, the part ``variable`` + would be emphasized and the escaped curly braces would be displayed: + :samp:`print(f"answer=\\{1+{variable}*2\\}")` + +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 some 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 intended for use by document translators + as a marker for the translation progress of the document. |