Sphinx Autodoc Is Needlessly Complicated

Sphinx and automatic documentation; where do I even begin!

I would hope that a solution similar to roxygen2 in R would exist; where I would simply write all the docstrings and run devtools::document() and it would all be done; however that is not the case for Python.

Here are the instructions which I had to source from two (yes two!) locations in order to make sense of it.

Perhaps you shouldn’t be generating all documentation automatically, however due to the nature of solo projects I think the reality is you want to depend on as much automation as possible and in that sense automatic documentation is the only sane way to do it.

The other advantage of automatic documentation rather than relying on Sphinx builds is the lack of cognitive shift needed to move from Markdown world to reStructuredText (granted it isn’t that much) and all savings are always welcomed.

This is the outline on how you can setup automatic documentation based on docstrings in Python.

Step 1

Assuming you have already installed Sphinx (otherwise run pip install sphinx), you can use CLI commands:

sphinx-quickstart doc -m
...
Project name: PROJECT_NAME
Author name(s): AUTHOR_NAME
Project version: VERSION
...

Replacing the relevant variables with the obvious names. This will create all the documentation related information in a directory doc which I would personally recommend.

Step 2

Navigate to conf.py and ensure the following lines are added. You may want to change the appropriate line for extensions as there might already be a template with this variable already assigned.

sys.path.insert(0, os.path.abspath('..'))
extensions = ['sphinx.ext.autodoc']

Step 3

Now when we are in the top directory, we can generate our documentation again using the Sphinx CLI tools:

sphinx-apidoc -o doc MODULE_NAME --force
cd doc
make html

You may wish to not have the --force switch if you do not want to overwrite the current documentation (but then what is the point of having documentation automatically generated by docstrings!).

Step 4 (Optional)

You may want to exclude certain modules (for example any tests) from having its documentation created. In order to add exclusions you simply need to add them to your conf.py file again to the exclude_patterns variable.

For example, if you followed this guide, and wish to ignore all tests modules, then the exclude_patterns variable probably looks something like this:

exclude_patterns = ['_build', '*.tests.rst']