reStructuredText

• reStructuredText demo package

For the language syntax documentation, read the ReST docutils syntax reference.

Fields

See fields section.

In addition to the standard set of fields, the reStructuredText parser also supports consolidated fields, which combine the documentation for several objects into a single field.

These consolidated fields may be written using either a bulleted list or a definition list.

• If a consolidated field is written as a bulleted list, then each list item must begin with the field’s argument, marked as interpreted text, and followed by a colon or dash.

• If a consolidated field is written as a definition list, then each definition item’s term should contain the field’s argument, (it is not mandatory for it being marked as interpreted text).

The following example shows the use of a definition list to define the Parameters consolidated field with type definition. Note that docutils requires a space before and after the : used to mark classifiers.

def fox_speed(size, weight, age):
    """
    :Parameters:
        size
            The size of the fox (in meters)
        weight : float
            The weight of the fox (in stones)
        age : int
            The age of the fox (in years)
    """

Using a bulleted list.

def fox_speed(size:float, weight:float, age:int):
    """
    :Parameters:
        - `size`: The size of the fox (in meters)
        - `weight`: The weight of the fox (in stones)
        - `age`: The age of the fox (in years)
    """

The following consolidated fields are currently supported by PyDoctor:

Consolidated Fields

Consolidated Field Tag	Corresponding Base Field Tag
:Parameters:	:param:
:Keywords:	:keyword:
:Exceptions:	:except:
:Variables:	:var:
:IVariables:	:ivar:
:CVariables:	:cvar:
:Types:	:type:

Fields are case insensitive.

Cross-references

PyDoctor replaces the Docutils’ default interpreted text role with the creation of documentation cross-reference links. If you want to create a cross-reference link to the module.Example class, simply put backticks around it, typing:

`module.Example`

Note

Sphinx interpreted text roles for code references like :obj: or :meth: are not required and will be ignored.

Directives

Here is a list of the supported ReST directives by package of origin:

• docutils: .. include::, .. contents::, .. image::, .. figure::, .. unicode::, .. raw::, .. math::, .. role::, .. table::, .. code::, .. warning::, .. note:: and other admonitions, and a few others.

• epydoc: None yet.

• Sphinx: .. deprecated::, .. versionchanged::, .. versionadded::, .. code-block::

• pydoctor: .. python::

Full list of supported and unsupported directives

Colorized snippets directive

Using reStructuredText markup it is possible to specify Python snippets in a doctest block.

If the Python prompt gets in your way when you try to copy and paste and you are not interested in self-testing docstrings, the python directive will let you obtain a simple block of colorized text. Directives .. code:: and .. code-block:: acts exactly the same.

.. python::

    def fib(n):
        """Print a Fibonacci series."""
        a, b = 0, 1
        while b < n:
            print b,
            a, b = b, a+b

Note

HTML element’s classes generated by our custom HTMLTranslator have a "rst-" prefix

Note

In any case, plaintext docstring format will be used if docstrings can’t be parsed with restructuredtext parser.