2.2.11. Documenting Python code with Sphinx¶
The goal of this tutorial is to teach you how to document Python code to help other programmers – and yourself in the future – understand your code. We recommend that you document each attribute, argument, method and class, and also document each module and package.
reStructuredText is the most commonly used markup format for documenting Python code and Sphinx is the most commonly used tool for compiling Python documentation.
2.2.11.1. Required packages¶
Execute the following commands to install the packages required for this tutorial:
apt-get install \
python \
python-pip
pip install \
configparse \ # configuration file parser
robpol86-sphinxcontrib-googleanalytics \ # sphinx support for Google analytics
sphinx \ # documentation generator
sphinx-rtd-theme # sphinx HTML theme
2.2.11.2. File naming and organization¶
Our convention is to place all top-level documentation within a separate docs directory within each repository and to embed all API documentation in the source code.:
/path/to/repo/
docs/ # directory for all of the documentation files
index.rst # main documentation file
conf.py # Sphinx configuration
requirements.txt # packages required to compile the documentation
requirements.rtd.txt # packages required to compile the documentation; used by Read the Docs
setup.cfg # contains a setting which specifies the packages for which
# API documentation should be generated
2.2.11.3. Generating a Sphinx configuration file¶
Sphinx is highly configurable and can be configured using the docs/conf.py file.
You can generate a Sphinx configuration file by running the sphinx-quickstart utility and following the on screen instructions.
Note: we are using a heavily modified Sphinx configuration file. See karr_lab_build_utils.templates.docs.conf.py for our template. In particular, we are enabling the napoleon extension to support Google-style argument and attribute doc strings.
2.2.11.4. Writing documentation¶
In the remainder of the tutorial, we will write tests for the code located in /path/to/this/repo/intro_to_wc_modeling/concepts_skills/software_engineering/unit_testing/.
Using the napoleon style, you can document each class, method, and attribute. See intro_to_wc_modeling/concepts_skills/software_engineering/unit_testing/core.py for a complete example.
2.2.11.4.1. Classes¶
class Class():
""" Description
Attributes:
name (:obj:`core.Simulation`): description
"""
...
2.2.11.4.2. Methods¶
def method():
""" Description
Args:
name (:obj:`type`): description
name (:obj:`type`, optional): description
Returns:
:obj:`type`: description
Raises:
:obj:`type`: description
"""
...
2.2.11.4.3. Top-level documentation¶
We can also add top-level documentation to docs/index.rst using the reStructuredText markup language. See the
reStructuredText primer for a brief tutorial
about the reStructuredText markup language.
2.2.11.4.4. README¶
In addition to this documentation, we also recommend providing a brief README file with each repository and we recommend embedded status badges at the top of this file. These badges can be embedded as shown in the example below:
<!-- [](https://pypi.python.org/pypi/intro_to_wc_modeling) -->
[](http://docs.karrlab.org/karrlab_intro_to_wc_modeling)
[](https://circleci.com/gh/KarrLab/intro_to_wc_modeling)
[](https://coveralls.io/github/KarrLab/intro_to_wc_modeling)
[](https://codeclimate.com/github/KarrLab/intro_to_wc_modeling)
[](LICENSE)
2.2.11.5. Compiling the documentation¶
Run the following to compile the documentation:
sphinx-build docs docs/_build/html
Sphinx will print out any errors in the documentation. These must be fixed to properly generate the documentation.
It can be viewed by opening docs/_build/html/index.html in your browser.