Technical an user documentation

The sphinx tool is a subset of docutils

Documenting a function

Info field lists

Inside Python object description 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. Creates a link if possible.
  • raises, raise, except, exception: That (and when) a specific exception is raised.
  • var: Description of a variable.
  • vartype: Type of a variable. Creates a link if possible.
  • returns, return: Description of the return value.
  • rtype: Return type. Creates a link if possible.

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:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

This will render like this with spinx-doc:

send_message(sender, recipient, message_body[, priority=1])

Send a message to a recipient

Parameters:
  • sender (str) – The person sending the message
  • recipient (str) – The recipient of the message
  • message_body (str) – The body of the message
  • priority (integer or None) – The priority of the message, can be a number 1-5
Returns:

the message id
Return type:

int
Raises:
  • ValueError – if the message_body exceeds 160 characters
  • TypeError – if the message_body is not a basestring

It is also possible to combine parameter type and description, if the type is a single word, like this:

:param int priority: The priority of the message, can be a number 1-5

Container types such as lists and dictionaries can be linked automatically using the following syntax:

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]

Multiple types in a type field will be linked automatically if separated by the word “or”:

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str