Autodoc Your Code¶

The Sphinx autodoc extension (see http://www.sphinx-doc.org/en/stable/ext/autodoc.html ) converts docstrings from your Python code into the final documentation format at Sphinx build-time.

This is very useful, but may not work out of the box. Here are some steps to set it up properly:

Tell autodoc how to Find your Code¶

Autodoc probably can’t find your code without a little help. Edit the docs/source/conf.py file. Uncomment:

import os
import sys

Uncomment and edit this line (adjust path as appropriate):

sys.path.insert(0, os.path.abspath('../../<PROJECT_NAME>'))

Submodules¶

If you have submodules, then you may need to use this path instead:

sys.path.insert(0, os.path.abspath('../..'))

One-Off Creation of RST Files¶

There is a script that you can run to create a directive file per Python module. You should only run this command once to set up the *.rst files.

In the docs directory, run this command to create rst files that document your python modules (Note that the -f option tells it to overwrite existing files):

sphinx-apidoc -f -o source/ ../<PROJECT_NAME>/

You should see rst files created in the docs/source/ folder

autodoc directives¶

The reStructuredText files for your Python modules in docs/source do not contain the docstrings. Instead they just contain directives on how to build the corresponding page.

They contain reStructuredText with directives to build the documentation from a particular Python module in your project. Example:

example_module module
=====================

.. automodule:: example_module
    :members:
    :undoc-members:
    :show-inheritance:

Example from this project, showing source RST and Python with resulting HTML:

reStructuredText:

example_module.rst

Python:

example_module.py

Auto-generated HTML:

example_module.html

Here are some additional directives that you may wish to add include:

Include private members, i.e. ones that start with an underscore
```
:private-members:
```
Include special members, i.e. ones that start and end with two underscores, such as __init__
```
:special-members:
```

Example using these extra directives:

reStructuredText:

example_module2.rst

Python:

example_module2.py

Auto-generated HTML:

example_module2.html

Documenting Your Code¶

While it is possible to use reStructuredText in the docstrings of your Python code, the author prefers to stay with plain text. Plain text docstrings still produce great HTML pages with autodoc. Ultimately, it is your choice.