...
- The type should be the lowest common denominator of the supported type. For example, if the type can be either a
str
or aunicode
, thenbasestring
should be specified. - If the type is a class, use
:class:`Name`
. - If multiple types are supported, separate them with a pipe (no spaces before or after the pipe).
- List types should have the element type embedded in brackets.
- Dict types should have the key and value types separate by a "," (space after the comma) and embedded in curly brackets.
- 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.
- Because Python is very dynamic, sometimes type does not matter much. In such cases do not use type
object
; instead omit the type information 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:
. 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
""" |
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
:vartype name: basestring
:ivar type_name: Type name
:vartype type_name: basestring
:ivar value: Value
:ivar description: Description
:vartype description: basestring |
Methods
Methods are documented identically to functions.
The only difference is that you should ignore the self
argument in documentation. Example:
Code Block | ||
---|---|---|
| ||
def release(self, time='now'): """ Release this resource. Do not use the resource after it has been released. :param time: when to release the resources, either 'now' or 'later' :type time: basestring :returns: ``True`` if released :rtype: bool """ |
Properties
Properties are documented similarly to methods.
Because they have no arguments, and always have a return value, only :rtype:
should be specified. Example:
Code Block | ||
---|---|---|
| ||
@property
def factory(self):
"""
The factory from which this resource was created.
:rtype: :class:`Factory`
""" |
Constructors
You can document Python's __init__
constructor just like any other method, however be aware that Sphinx will add the content after the class docstring. (This reflects the fact that the symbol itself is used as a constructor function in Python.)
This feature can lead to confusing results. For this reason, we recommend not adding anything to the __init__
docstring other than the argument description block. Put all relevant English descriptions in the class docstring instead.