Page History

...

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:

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:

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

...