...
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: 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 |
...