Document your project¶
Document your Python code using Python’s native tools and practices. Normally you should supply these three kinds of documentation:
- docstrings to describe all your modules, functions and classes, particularly their overall functions and what properties they expect their arguments to have.
- comments to explain mysteries in your code which aren’t already explained by naming things carefully, or in docstrings.
- A Sphinx project which can be used to build your reference and narrative documentation.
How are docstrings used?
- Read by humans in the source code.
- Used by help() and the
pydocutility to provide help on the stuff you wrote.
- Extracted by Sphinx autodoc so you can insert them into your documentation.
How to write good docstrings? For starters:
- Be familiar with the PEP 8 section on docstrings.
- Be familiar with PEP 257.
- Be familiar with PEP 287.
How to use docstrings¶
As a rule, put a triple-quoted string just inside the definitions of most functions, classes and methods. Here’s an example:
def f(): """First line describing what the function is for. Subsequent lines of explanation. More explanation until we reach 72 columns, then wrap to the next line. Another paragraph of explanation could be here if you wanted it. :returns: description of possible return values. """ return 2
Breaking down the components of this docstring:
- First line: what does the documented function do, why does it exist?
- Then one empty line if there is any more to say.
- Then one or more paragraphs on what the function does.
- Then you can put in arg/return value type annotations, possibly in Sphinx RST format. For each one, explain your expectations for the arguments and what others should expect from this.
Methods and classes can be treated in essentially the same way.
Use Sphinx to build documentation in many different formats. It basically works as follows: you write files in a relatively simple format called reStructuredText, and Sphinx uses those to build documentation in any of several different formats (e.g. HTML), in the same general style used by many other Python projects as well as Python itself.
Here’s what Sphinx does for you:
- Extracts docstrings from your source code to include in the generated docs.
- Lets you integrate this automatically extracted stuff with whatever narrative documentation you write.
- Can run doctests in your documentation (useful to avoid broken examples, which users find very frustrating).
To learn how to use Sphinx, check out the fine Sphinx tutorial. Most Python projects should also pay special attention to Sphinx’s autodoc extension, which does the job of extracting and reStructuredText markup from your docstrings to help you generate API documentation more easily. (It doesn’t fully automate the process, but such docs tend to be of pretty bad quality anyway.) You may also be interested in Sphinx’s doctest extension, to test snippets of code that are embedded in your documentation.
There are other documentation generators but Sphinx is the most standard and arguably the best; it’s used for Python itself and lends itself to writing properly explanatory, human-readable documentation rather than just an autogenerated catalog of functions and classes.
If you want to self-host your Sphinx docs on the web, you can use any static
file host, just deploy the html produced by
Assuming your host can be configured to serve foo/index.html for requests of
foo/, you can get clean URLs by using the ‘dirhtml’ build target for Sphinx
make dirhtml); instead of foo.html, this generates foo/index.html.