...
Function arguments, return values, and class properties are all marked up tagged twice: once is the English description, next is the type. The exact prefixes will be detailed later when used.
...
In the class docstring add a section to document all arguments and return value. Arguments are documented with :param:
and :type:
. The return value is documented with :returns:
and :rtype:
.
If the function raises exceptions, these should be specified via one or more :raises:
descriptors, after the params and return descriptors. Note that Sphinx will create a link to the name of the exception class, so feel free to use the full Python path if necessary.
Complete example:
Code Block | ||
---|---|---|
| ||
def release_resources(factory, time='now'):
"""
Release all instances of :class:`Resource`.
:param factory: factory holding the resources
:type factory: :class:`Factory`
:param time: when to release the resources, either 'now' or 'later'
:type time: basestring
:returns: ``True`` if released at least one resource
:rtype: bool
:raises AttributeError: if ``factory`` is not a :class:`Factory` subclass instance
:raises ValueError: if ``time`` is not 'now' or 'later'
:raises aria.exceptions.FactoryError: if the factory is not properly configured
""" |
Classes
Fields
In the class docstring make sure to add a section where you document all its fields in a separate block using :ivar:
and :vartype:
(ivar here stands for "instance variable"). Example:
Code Block | ||
---|---|---|
| ||
Represents a typed value. The value can contain nested intrinsic functions.
This model can be used as the ``container_holder`` argument for :func:`functions.evaluate`.
:ivar name: unique name in factory
:vartype name: basestring
:ivar type_name: type name from factory type registrar
:vartype type_name: basestring
:ivar value: arbitrary value; cannot be ``None``
:ivar description: English one-line description
:vartype description: basestring |
...