Table of content
Introduction
It's important for a project to have a good documentation, or, at least, a documentation. Especially concerning a library, or a module to be integrated in other programs. The user should have access to a description of functions and their parameters.
Fortunately, Python offers really powerful mechanisms to explore its objects and functions extracting any found documentation dynamically. Furthermore, tools like Sphinx generate a real documentation for the web publishing from docstrings analysis.
There is some documentation around the Python documentation management starting by PEP8 and PEP257, but also the Python devguide, or this. However, there isn't so much about showing several formats together.
In this tuto you can find information and examples about the main docstrings formats.
Docstrings
First of all, a docstring stands for "documentation string" that is a special comment in Python.
The docstrings are special Python strings describing each element of interest (functions, classes, methods, variables). However the developer should write those docstrings respecting a particular syntax convention. The docstring is not only addressed to the developer, but also to the users.
Note that the PEP8 presents very briefly the notion of documentation strings and refers to PEP257 that is not really reacher and provides few examples (with a syntax not really widespread).
Formats
Let's see the main available syntax formats for the Python docstrings:
- reStructuredText, probably the most popular for Python docstrings format, with several forms also and that is mainly used in conjonction with Sphinx. Note that this format is used for the Python documentation.
- Epytext (Javadoc based), that was used years ago for Python but can still be found
- Google style, that can take several forms
- Numpydoc, looks like Google docs, used for the numpy related projects (but not only)
Python doc introspection
When running Python interpreter, you can get an interactive help about a module or anything else documented with dosctrings using the function help():
>>> import os
>>> help(os)
It is also possible to get the description of an element by accessing its __doc__ property (corresponding to its docstring):
>>> import os
>>> print os.path.__doc__
External docs generation
As Python knows how to provide a documentation to the user extracting the docstrings, external tools can generate a documentation parsing the Python modules.
For instance, Doxygen generates HTML pages (and many other output formats) for C/C++ programs parsing code and parsing formated comments placed before the functions. It can also manage Python language but it is not really adapted regarding Sphinx. Java has it own documentation generator called Javadoc that inspired Epydoc for Python in old times.
Sphinx
The most popular documentation generator for Python is Sphinx. It converts reStructuredText docstring format input to many possible output formats as HTML, PDF, LaTeX, manuals. There are also plugins allowing to use other formats as Numpydoc, Google,... You can have a look there to find examples.
Epydoc
An old popular documentation generator is Epydoc that converts Epytext docstring format (based on Javadoc) to output readable formats as HTML.
Main formats description
As said before, there are several available formats to use in docstrings in order to build a documentation about the code. You will find in this section the mentioned formats described and some examples of how to use them.
reStructuredText
Descritption
As Sphinx uses this format by default, it is a very popular one for Python docstrings.
It is a fromat very reach, not only for docstrings. the reST format is widely used as Markdown format for documenting (Github, Pelican, wikis,...). Note that this blog - and the lines you are currently reading - is generated by Pelican using reStructured Text format.
Parameters
reStructuredText format is very reach. Thus it is possible to represent things in several ways. It is the case of the parameters and their types. Of course you can specify only the parameter.
As for Javadoc format, the parameters can be represented separately from the types:
"""
:param param1: Description of param1
:type param1: str
"""
Or it is possible to represent the parameter together with its type:
"""
:param param1 str: Description of param1
"""
Returned value
A description of what is returned can be specified as following:
"""
:return: Description of what is return
"""
It is also possible to provide the returned type:
"""
:rtype: str
"""
Raised exceptions
Each exceptions should be described using the raises keyword followed by the exception label and its description:
"""
:raises MyError: Description of my error
"""
Numpydoc
Descritption
Numpy recommend to use their own docstring format that looks like Google docstring format, and uses also some reST syntax elements. There is a plugin for Sphinx to accept Numpydoc format. You can refer to this documentation.
Parameters
The parameters are specified in a common section named Parameters. For each wanted parameter, you should specify its name, a white space, a colon and then its type with other options. The description is indented underneath. To refer to the parameter, you may surround it using `.
There is some examples:
1 """
2 Parameters
3 ----------
4 param1 : int
5 Description of parameter `param1`.
6 param2 : {'value1', 'value2'}
7 Description of a parameter with two possible values.
8 paramX, paramY : array_like
9 Parameter array.
10 param3 : list of str, optional
11 Description of parameter `param3`.
12 Its default value is ["value"].
13 """
Returned value
As for parameters, the returned values are managed in a specific section. That section is identified by the keyword Returns and underlined.
The type must be provided in a line, and the next line should contain the description indented:
"""
Returns
-------
int
Description of the returned value
"""
It is also possible to name the returned values:
"""
Returns
-------
ret1 : int
Description of returned number.
ret2 : str or None
Description of string alternative.
"""
Raised exceptions
The raising exception section is labeled "Raises" and contains the exceptions list with description following on second intended line:
"""
Raises
------
MyError:
Description of my error
MyOtherError:
Description of an other error
"""
Googledoc
Descritption
The Google docstring style is as you can guess used and supported by Google, but not only. It is also popular and used in several forms, Numpydoc is a kind of. You can find informations in the Google style guide concerning Python comments. You will also find some examples there.
Parameters
The parameters are specified in the common section Args. The parameter's type is provided inside parenthesis. The keyword optional specify that the parameter has a default value. To refer to the parameter, you may surround it using `.
"""
Args:
param1(int): Description of parameter `param1`.
param2(str, optional): Description of a parameter. Defaults to None.
"""
Returned value
A section for returned values is named Returns and returned description is then listed starting with the returned type.
"""
Returns:
bool: True or False depending on the result.
"""
Yields
As for returned section, a Yields section relate to the yielded elements.
"""
Yields:
int: The next yield value.
"""
Raised exceptions
The raising exception section is labeled "Raises" and contains the exceptions list with description following on second intended line:
"""
Raises:
MyError: Description of my error that was
raised
MyOtherError: Description of an other error
"""
Javadoc/Epytext
Descritption
The Epytext, or Javadoc style, was inspired from Java world before the arrival of the reStructuredText format. Some years ago it was frequently used for Python docstrings. The Epydoc software, first released in 2002 but now discontinued, was converting the Epytext format very similar to Javadoc to HTML or PDF.
Parameters
The way to describe the parameters is close to the reST manner.
"""
@param param1: Description of param1
"""
You can also specify a type precising the parameter name:
"""
@type param1: str
"""
Returned value
A description of what is returned can be provided as following:
"""
@return: Description of what is return
"""
It is also possible to provide the returned type:
"""
@rtype: str
"""
Raised exceptions
The raised exceptions in a function can be given with the label of the exception and its description:
"""
@raise MyError: Description of my error
"""
Old school/Customized
You can of course have your own way to write docstrings or not commenting at all but it's not adapted for reusing, evoluting, sharing...
Conclusion
This is a short overview about the docstrings and main formats. Don't hesitate to go further with the provided references and Internet researches.
You may also explore existing tools like Sphinx to generate the documentation or Pyment (hosted on Github) to generate or convert docstrings of Python files.