Python Doc Generation with Sphinx

After getting up and running with automate unittest, coverage visualisation, linter, and formatting; now we are going to add 1 step further for our development practice in Python — How to document our works.

This article is a rather opinionated works, and aim for the simplest way to generate readable document.

Generated Documentation

Activity Outline

By large the activity of creating a document consists of 3 steps

1. Ensuring all Dependencies are ready
2. Initialising the Documentation
   In this step some manual setup and writes are required. This article shall provides a simple layout to make it easier to auto-build later on. The concept is to automate the presentation out of writing README.rst and Python Docstrings
3. Build The Docs
   This describes how to build the docs, collecting your changes on README and Docstring, and build the updated docs

We shall do sample works on this based on the project of https://gitlab.com/suekto.andreas/python-dev-setup/tags/v1.0.0

Prerequisite

Let us install the dependencies for this project. Sphinx is the main tool to generate documentation. While sphinx_rtd_theme is a theme that I personally like, therefore you can always skip / modify this part without losing much of functionality.

$ . venv/bin/activate
$ pip install sphinx
$ pip install sphinx_rtd_theme

Initialising Docs

Step1 — We gonna use the `sphinx-quickstart`.

It shall provides you with queries to build a basic source code for the Docs. Let’s start the action

$ . venv/bin/activate
$ mkdir docs
$ cd docs
$ sphinx-quickstart # queries on basic setup shall starts

The following are points to be ensured:

1. Separate source and build directories: y
2. autodoc: automatically insert docstrings from modules : y
3. Create Makefile? : y

Be careful on `viewcode: include links to the source code of documented Python objects (y/n)`. At this point a directory named docs/source is created.

Step2 — Setup the autodoc path in docs/source/conf.py

Find the line called Path Setup, normally the 3 lines are commented, ensure it is being uncommented, and setup the path to the directory where your source code is.

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
# this conf.py is in ./docs/source/conf.py
# therefore our source code is up 2 level then the directory of python source code is the i.e. ./python_dev_setup

Step3 — Set the Theme to use RTD theme

inside the ./docs/source/conf.py

html_theme = 'sphinx_rtd_theme'

Step4 — index.rst

overwrite the ./docs/source/index.rst as per below. The top `Python Dev Environment in VSCode` is the doc title, change it accordingly to your project specific.

Python Dev Environment in VSCode
====================================================================
.. toctree::
   :maxdepth: 2
   :caption: Readme
   readme
.. toctree::
   :maxdepth: 2
   :caption: Docstring
   docstring/modules
.. toctree::
   :maxdepth: 2
   :caption: Index
   indices

below the toctree are relative pointer to another rst files under source directory, those 3 rst are going to be created in the next steps.

Step5 — readme

we are going to create a proxy file towards our project root README.rst, so that it can be taken in by toctree.

$ vi docs/source/readme.rst

then write in the following script

.. include:: ../../README.rst

Step6 — indices

This is describing links to document index

$ vi docs/source/indices.rst

write in

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Build the Docs

Now we are going to build the docs this is accomplished by running the following commands

$ . venv/bin/activate
$ rm -Rf docs/build
$ rm -Rf docs/source/docstring
$ sphinx-apidoc -f -o docs/source/docstring/ python_dev_setup # this is the steps where the docstring/modules going to be filled with our code docstring
$ cd docs && make html && cd ..

noticed the sphinx-apidoc call, its the essence of automatically creating documentation out of our written docstring in our modules (in this case the folder is in multiply, change this into your project corresponding directory)

we provide a helper scripts to build in tools/build-doc.sh

#!/usr/bin/env bash
SOURCE_CODE_PATH=$1
. venv/bin/activate
rm -Rf docs/build
rm -Rf docs/source/docstring
sphinx-apidoc -f -o docs/source/docstring/ $SOURCE_CODE_PATH
cd docs && make html && cd ..

So we can deliver the same action through only 1 line of command

$ . tools/build-doc.sh python_dev_setup

That’s it ! by this steps you should be able to see there is a build directory (./docs/build) with index.html inside where you can open it up in browser, and there you are served with your static html doc !

Conclusion

With this steps, everytime you expand your project by simply writing the README.rst, or your Python’s docstring your beautifully written HTML doc shall be served just by running 1 command line !

Gitlab: https://gitlab.com/suekto.andreas/python-dev-setup/tags/v1.2.0