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.
By large the activity of creating a document consists of 3 steps
- Ensuring all Dependencies are ready
- 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
- 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
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
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:
- Separate source and build directories: y
- autodoc: automatically insert docstrings from modules : y
- 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.
# 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
:caption: Readme readme.. toctree::
:caption: Docstring docstring/modules.. toctree::
: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
Indices and tables
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 bashSOURCE_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 !
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 !