Page History

...

Note that if you don't have a paragraph prior to your code, use a paragraph that is just "::" in which case Sphinx will not render a colon.

Attributes, Parameters, Arguments, Return Values

Values

Function arguments, return values, and class properties are all tagged All of these are marked up twice: once is the English description, next is the type. The exact prefixes will be detailed later when used.

...

1. The type should be the lowest common denominator of the supported type. For example, if the type can be either a str or a unicode, then basestring should be specified.
2. If the type is a class, use :class:`Name``Resource`.
3. If multiple types are supported, separate them with a pipe (no spaces before or after the pipe).: int|bool|FunctionType
4. List types should have the element type embedded in brackets.: [int], [int|:class:`Resource`]
5. Dict types should have the key and value types separate by a "," (space after the comma) and embedded in curly brackets.: {basestring, :class:`Resource`}
6. If None is a possible value, do not specify the type as None or NoneType. None values are not truly typed, but instead are treated specially everywhere in Python. In such cases, explain in the English description how None values are treated, if at all.
7. Because Python is very dynamic, sometimes type does not matter much. In such cases do not use type object; instead omit the type information descriptor altogether.

Functions

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: Name unique name in factory
:vartype name: basestring
:ivar type_name: Typetype name from factory type registrar
:vartype type_name: basestring
:ivar value: Value arbitrary value; cannot be ``None``
:ivar description: Description English one-line description
:vartype description: basestring

...