Source

sphinx / Doc-3k / documenting / markup.rst

Full commit

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

Meta-information markup

Module-specific markup

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 <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

As you can see, the module-specific markup consists of two directives, the module directive and the moduleauthor directive.

Note

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.

Information units

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)
    • c
    • rest
    • 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:

Inline markup

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.

Cross-linking markup

To support cross-referencing to arbitrary sections in the documentation, the standard reST labels are "abused" a bit: Every label must precede a section title; and every label name must be unique throughout the entire documentation source.

You can then reference to these sections using the :ref:`label-name` role.

Example:

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

The :ref: invocation is replaced with the section title.

Paragraph-level markup

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


Table-of-contents markup

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.

Index-generating markup

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.

For example:

.. 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:

single
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
pair: loop; statement is a shortcut that creates two index entries, namely loop; statement and statement; loop.
triple
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`

Substitutions

The documentation system provides three substitutions that are defined by default. They are set in the build configuration file, see :ref:`doc-build-config`.