Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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`.
  3. If multiple types are supported, separate them with a pipe (no spaces before or after the pipe).
  4. List types should have the element type embedded in brackets.
  5. Dict types should have the key and value types separate by a "," (space after the comma) and embedded in curly brackets.
  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 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
languagetext
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
languagetext
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
languagetext
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
languagetext
@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.