sphinx / doc / markup / desc.rst

Module-specific markup

The markup described in this section is used to provide information about a module being documented. Normally this markup appears after a title heading; a typical module section 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>

The directives you can use for module declarations are:


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.

Object description 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)

   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:


Signatures of functions, methods and class constructors can be given like they would be written in Python, with the exception that optional parameters can be indicated by brackets:

.. function:: compile(source[, filename[, symbol]])

It is customary to put the opening bracket before the comma. In addition to this "nested" bracket style, a "flat" style can also be used, due to the fact that most optional parameters can be given independently:

.. function:: compile(source[, filename, symbol])

Default values for optional arguments can be given (but if they contain commas, they will confuse the signature parser). Python 3-style argument annotations can also be given as well as return type annotations:

.. function:: compile(source : string[, filename, symbol]) -> ast object

Info field lists

Inside description unit directives, reST field lists with these fields are recognized and formatted nicely:

  • param, parameter, arg, argument, key, keyword: Description of a parameter.
  • type: Type of a parameter.
  • raises, raise, except, exception: That (and when) a specific exception is raised.
  • var, ivar, cvar: Description of a variable.
  • returns, return: Description of the return value.
  • rtype: Return type.

The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:

.. function:: format_exception(etype, value, tb[, limit=None])

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings

This will render like this:

Command-line program markup

There is a set of directives allowing documenting command-line programs:

Custom description units

There is also a generic version of these directives:

Extensions may add more directives like that, using the :func:`~sphinx.application.Sphinx.add_description_unit` method.