...
- Python docstrings should always appear on the line underneath the symbol they are attached to.
- Docstrings will be indented once off the symbol they are attached to.
- We will normally use multi-line docstrings with triple-double-quote delimiters.
- The delimiters will each appear on their own line. (Note that in some Python guides, the first delimiter does not appear on its own line. The archaic reason for this is that it adds an extra newline at the beginning of the docstring, but this is irrelevant when one uses markup languages like reST.)
- Line lengths throughout the entire block should be limited to same number of columns as code (100 columns). Wrap whole words to the next line; prefer never to hyphenate.
- We will normally add an extra empty line after the docstring, neatly separate it from code.
If the docstring is very short, it's permissible to put delimiters and content all in one line and avoid the extra empty line. Only do this if the content fits in a single line within the allowed column limit (100).
English
...
Descriptions
The point is to succinctly describe what the symbol is for, what it does, how it behaves, and how to use it.
- If its usage is specific, it would also be good to specify where it is used (which modules, classes, mechanisms, etc.).
- Use several paragraphs as necessary. Each paragraph should start at column 0 and have an empty line separating it from the next section.
- The first paragraph should be as short as possible: it is a quick description that should be enough for a programmer familiar with the code. It can even be a fragment rather than a complete grammatical sentence. Subsequent paragraphs will delve into more detail.
Avoid using the name or type of the symbol itself, as it is redundant. This is bad:
Code Block | ||
---|---|---|
| ||
Parameter is a class that wraps value and gives them a strict type. |
This is better:
Code Block | ||
---|---|---|
| ||
Wraps values and provides a strict type. |
Markup
Emphasis
- *asterisk for italics*
- **double-asterisk for bold**
Escape Special Characters
Sphinx is aggressive about interpreting special characters, and not very good at automatically detecting when you don't want it to interpret them. Make sure to escape them with a backslash.
So, if you want to use an asterisk as is, make sure to escape it:
Code Block | ||
---|---|---|
| ||
Uses value \* unit size / 2.0 to calculate the final frequency. |
Another common annoyance is the underscore. This would render incorrectly:
Code Block | ||
---|---|---|
| ||
Do not delete the value of user_password. |
Instead, do this:
Code Block | ||
---|---|---|
| ||
Do not delete the value of user\_password. |
(Actually, it's probably better to use double-back-quotes to render symbols, in which case you do not have to escape underscores. See below.)
Symbols
The safest way to mention an arbitrary symbol is to embed it in double-back-quotes. Example:
Code Block | ||
---|---|---|
| ||
The ``user_password`` field in the result will contain the generated password. |
The single-back-quote delimiter is used only for linked Python symbols. Sphinx can sometimes find the symbol automatically, but is often wrong, especially if there is ambiguity. It is thus best to prefix the single-back-quoted symbol with the type of the symbol, and also provide full Python paths if it's not immediately within the code block. The following prefixes are supported:
:class:
Class name. Always provide the full Python path, even if it's within the same module.:func:
Global function name. Always provide the full Python path, even if it's a global method within the same module.:meth:
Method name. You do not have to provide the full Python path if it's a method within the same class as the docstring.
Examples:
Code Block | ||
---|---|---|
| ||
The :meth:`release` method in this class should be used to release all resources when done. Do
not use the instance after it has been released. To release all instances, you may use the
:func:`aria.tools.release_all` global function. |
Hyperlinks
Use back-quotes with the URL in triangle-quotes followed by double-underscore. Example:
Code Block | ||
---|---|---|
| ||
This is a `link to a website <http://mysite.org/page>`__. |
While the double-underscore is not strictly required, it tells Sphinx to avoid an annoying optimization by which it groups identical links together and turns them into footnotes, making the documentation harder to read. The double-underscore tells Sphinx to always render the link as is, and so is always safe for all links.
URLs can be wrapped across multiple lines. Prefer to break the hyperlink before URL separators ("/", "#", "?", etc.). Example:
Code Block | ||
---|---|---|
| ||
See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
#DEFN_ENTITY_NODE_TEMPLATE>`__ |
Code Blocks
This is surprisingly easy in reST. Simply end the previous paragraph in double-colon and indent the code block. Sphinx will render a single colon and put your paragraph as is. Example:
Code Block | ||
---|---|---|
| ||
Usage example:: x = Resource() try: if x.valid: x.display() finally: |
...
x.destroy()
Make sure to properly destroy the resource as shown above. |
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.
Values
Function arguments, return values, and class properties are all tagged twice: once is the English description, next is the type. The exact prefixes will be detailed later when used.
Note that if the description must be split into multiple lines, Sphinx requires that subsequent lines be indented. Example:
Code Block | ||
---|---|---|
| ||
:param output: specifies that the phase has a *single* output; note that actual path of the
output will be based on this parameter but not identical to it |
Description
- The English description is a non-capitalized fragment. It should not end in a period.
- Do not add "the" at the beginning of the description, unless absolutely necessary to provide clarity.
- Do not add "of the class" or "of the instance" unless absolutely necessary to provide clarity.
- If more details must be added, add extra fragments using a semicolon.
Type
- 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:`Resource`
. - If multiple types are supported, separate them with a pipe (no spaces before or after the pipe):
int|bool|FunctionType
- List types should have the element type embedded in brackets:
[int],
[int|:class:`Resource`]
- Dict types should have the key and value types separate by a "," (space after the comma) and embedded in curly brackets:
{basestring, :class:`Resource`}
- 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 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:
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: 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 |
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.
Markup