directives.rst

rst

Directives

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 /usage/restructuredtext/domains for roles added by domains.

Refer to the reStructuredText Primer <rst-directives> for an overview of the directives provided by Docutils.

Table of contents

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 include directive.

Note

To create table of contents for current document (.rst file), use the standard reST contents directive <table-of-contents>.

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 object descriptions <basic-domain-markup>, and from :rstindex directives.

  The Python module index contains one entry per :rstpy: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

note, warning pair: changes; in version

These directives create short paragraphs and can be used inside information units as well as normal text.

Showing code examples

pair: code; examples single: sourcecode

There are multiple ways to show syntax-highlighted literal code blocks in Sphinx:

• using reST doctest blocks <rst-doctest-blocks>;
• using reST literal blocks <rst-literal-blocks>, optionally in combination with the :rsthighlight directive;
• using the :rstcode-block directive;
• and using the :rstliteralinclude 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 :rstcode-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 :rstliteralinclude directive is useful for including entire code files in your documentation.

In all cases, Syntax highlighting is provided by Pygments. When using literal blocks, this is configured using any :rsthighlight 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 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 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.

Glossary

Meta-information markup

Index-generating markup

Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in /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.

Including content based on tags

Tables

Use reStructuredText tables <rst-tables>, i.e. either

• grid table syntax (ref <grid-tables>),
• simple table syntax (ref <simple-tables>),
• csv-table syntax,
• or list-table syntax.

The table directive serves as optional wrapper of the grid and simple syntaxes.

They work fine in HTML output, however there are some gotchas when using tables in LaTeX: the column width is hard to determine correctly automatically. For this reason, the following directive exists:

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 autodoc <sphinx.ext.autodoc>, you either have to double all backslashes, or use Python raw strings (r"raw").

math-support

Rendering options for math with HTML builders.

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:

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`

Footnotes