jesugmz/Python-docstring-restructuredtext-style.rst

## Python-docstring-restructuredtext-style.rst

      
    Raw
  

              Python-docstring-restructuredtext-style.rst
            
          
    Python docstring reStructuredText style

Python Signatures

Signatures of functions, methods and class constructors can be given like they would be written in Python.
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:
.. py:function:: compile(source : string, filename, symbol='file') -> ast object
For functions with optional parameters that don't have default values (typically functions implemented in C extension modules without keyword argument support), you can use brackets to specify the optional parts:


It is customary to put the opening bracket before the comma.
Info field lists


0.4

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, ivar, cvar: 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.


Note

In current release, all var, ivar and cvar are represented as "Variable". There is no difference at all.

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:


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

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
Cross-referencing Python objects

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, :py:func:`filter` could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :py:func:`foo.filter` clearly refers to the filter function in the foo module.
Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python's codecs module, :py:func:`open` always refers to the built-in function, while :py:func:`.open` refers to codecs.open.
A similar heuristic is used to determine whether the name is an attribute of the currently documented class.
Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:`.TarFile.close` references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.
Note that you can combine the ~ and . prefixes: :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close() method, but the visible link caption will only be close().