Additional Markup Constructs
Sphinx adds a lot of new directives and interpreted text roles to standard reST markup. This section contains the reference material for these facilities. Documentation for "standard" reST constructs is not included here, though they are used in the Python documentation.
XXX: file-wide metadata
The markup described in this section is used to provide information about a module being documented. Each module should be documented in its own file. Normally this markup appears after the title heading of that file; a typical file might start like this:
:mod:`parrot` -- Dead parrot access =================================== .. module:: parrot :platform: Unix, Windows :synopsis: Analyze and reanimate dead parrots. .. moduleauthor:: Eric Cleese <email@example.com> .. moduleauthor:: John Idle <firstname.lastname@example.org>
As you can see, the module-specific markup consists of two directives, the module directive and the moduleauthor directive.
It is important to make the section title of a module-describing file meaningful since that value will be inserted in the table-of-contents trees in overview files.
There are a number of directives used to describe specific features provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description. The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:. The following example shows all of the features of this directive type:
.. function:: spam(eggs) ham(eggs) :noindex: Spam or ham the foo.
The signatures of object methods or data attributes should always include the type name (.. method:: FileInput.input(...)), even if it is obvious from the context which type they belong to; this is to enable consistent cross-references. If you describe methods belonging to an abstract protocol, such as "context managers", include a (pseudo-)type name too to make the index entries more informative.
The directives are:
There is also a generic version of these directives:
Showing code examples
Examples of Python source code or interactive sessions are represented using standard reST literal blocks. They are started by a :: at the end of the preceding paragraph and delimited by indentation.
Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output presented, there should not be an "unused" primary prompt; this is an example of what not to do:
>>> 1 + 1 2 >>>
Syntax highlighting is handled in a smart way:
There is a "highlighting language" for each source file. Per default, this is 'python' as the majority of files will have to highlight Python snippets.
Within Python highlighting mode, interactive sessions are recognized automatically and highlighted appropriately.
The highlighting language can be changed using the highlightlang directive, used as follows:
.. highlightlang:: c
This language is used until the next highlightlang directive is encountered.
The valid values for the highlighting language are:
- python (the default)
- none (no highlighting)
If highlighting with the current language fails, the block is not highlighted in any way.
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 standard include directive with the literal option flag. For example, to include the Python source file :file:`example.py`, use:
.. include:: example.py :literal:
As said before, Sphinx uses interpreted text roles to insert semantic markup in documents.
The default role is var, as that was one of the most common macros used in the old LaTeX docs. That means that you can use `var` to refer to a variable named "var".
For all other roles, you have to write :rolename:`content`.
The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found:
The name enclosed in this markup can include a module name and/or a class name. For example, :func:`filter` could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :func:`foo.filter` clearly refers to the filter function in the foo module.
A similar heuristic is used to determine whether the name is an attribute of the currently documented class.
The following roles create cross-references to C-language constructs if they are defined in the API documentation:
The following role does possibly create a cross-reference, but does not refer to objects:
The following roles don't do anything special except formatting the text in a different style:
The following roles generate external links:
Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose.
These directives create short paragraphs and can be used inside information units as well as normal text:
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.
Sphinx automatically creates index entries from all information units (like functions, classes or attributes) like discussed before.
However, there is also an explicit directive 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.
The directive is index and contains one or more index entries. Each entry consists of a type and a value, separated by a colon.
.. index:: single: execution!context module: __main__ module: sys triple: module; search; path
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).
The possible entry types are:
- Creates a single index entry. Can be made a subentry by separating the subentry text with a semicolon (this is also used below to describe what entries are created).
- pair: loop; statement is a shortcut that creates two index entries, namely loop; statement and statement; loop.
- Likewise, triple: module; search; path is a shortcut that creates three index entries, which are module; search path, search; path, module and path; module search.
- module, keyword, operator, object, exception, statement, builtin
- These all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module.
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`
The documentation system provides three substitutions that are defined by default. They are set in the build configuration file, see :ref:`doc-build-config`.