reStructuredText
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 Field Tag |
Corresponding Base Field Tag |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.