Docstrings¶
With the Sphinx extension sphinx.ext.autodoc, docstrings can also be included in the documentation. The following three directives can be specified:
These document a module, a class or an exception using the docstring of the respective object.
Installation¶
sphinx.ext.autodoc
is usually already specified in the Sphinx configuration
file docs/conf.py
:
extensions = [
'sphinx.ext.autodoc',
...
]
If your package and its documentation are part of the same repository, they will
always have the same relative position in the filesystem. In this case you can
simply edit the Sphinx configuration for sys.path
to indicate the relative
path to the package, so:
sys.path.insert(0, os.path.abspath('..'))
import requests
If you have installed your Sphinx documentation in a virtual environment, you can also install your package there with:
$ python -m pip install my.package
or, if you want to develop the package further with:
$ python -m pip install -e https://github.com/veit/my.package.git
Examples¶
Here are some examples from the API documentation for the requests module:
Docstrings example
==================
Developer Interface
-------------------
.. module:: requests
Main Interface
--------------
.. autofunction:: head
Exceptions
----------
.. autoexception:: requests.RequestException
Request Sessions
----------------
.. autoclass:: Session
:inherited-members:
This leads to the Docstrings example, generated from the following docstrings:
Note
You should follow these guidelines when writing docstrings:
sphinx-autodoc-typehints
¶
With PEP 484 a standard method for expressing types in Python code was introduced. This also allows types to be expressed differently in docstrings. The variant with types according to PEP 484 has the advantage that type testers and IDEs can be used for static code analysis.
Python 3 type annotations:
def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Args: arg1: Description of arg1 arg2: Description of arg2 Returns: Description of return value """ return True
Types in Docstrings:
def func(arg1, arg2): """Summary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value """ return True
Note
- PEP 484#suggested-syntax-for-python-2-7-and-straddling-code are currently
not supported by Sphinx and do not appear in the generated documentation.
sphinx.ext.napoleon
¶
The sphinx extension sphinx.ext.napoleon allows you to define different sections in docstrings, including:
Attributes
Example
Keyword Arguments
Methods
Parameters
Warning
Yield
There are two styles of docstrings in sphinx.ext.napoleon
:
The main differences are that Google uses indentations and NumPy uses underscores:
Google:
def func(arg1, arg2): """Summary line. Extended description of function. Args: arg1 (int): Description of arg1 arg2 (str): Description of arg2 Returns: bool: Description of return value """ return True
NumPy:
def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value """ return True
You can find the detailed configuration options in sphinxcontrib.napoleon.Config.