What do the Pyramids & Python have in common?

Oops! With a dog emergency this week, and just generally a busy week I overlooked scheduling this post for yesterday.

But here it is now! Hope you enjoy the read.

[rating: intermediate]

Last week I wrote about using docstrings in Python code for improved documentation. Docstrings by themselves are really useful. In certain situations they become even more useful when combined with the sphinx tool.

Beyond that, the sphinx tool also enables more general documentation to be stored in the same repository as source code. Perfect for documentation that has the same release cadence as the source code.

What’s the point?

As a business we want as little duplicated effort as possible. If customer support staff are writing documentation of software because it isn’t provided in a format that can be consumed by customers, or because it isn’t provided at all by developers, then we can use tools like Sphinx to efficiently fill that gap. Developers & others can generate the source documentation in the repository with the source code & the documentation can be rendered into various formats as needed.

Maybe a Wiki is a better choice?

It could be. The problem is that Wiki content such as Confluence is not in the same repository as the source code. This is fine for content that does not have the same release cadence as the application. But for documentation that is release aligned with source code, then the most effective way to naturally maintain the synchronization between application & documentation is to maintain both in the same repository.

Github/Gitlab Pages may also be a suitable choice since the documentation source content is in the repository with application source code. But now that documentation is connected specifically to Github or Gitlab for distribution - a kind of vendor lock-in - & this might not be suitable for distributing to customers. Security considerations might not allow exposing an internal site to customers on the public Internet, or budgets might not allow for provisioning a new Github/Gitlab instance for use by customers along with the cost & time to integrate the new instance with your internal instance.

Lots of good judgement required.

Using sphinx

The basis of the sphinx tool is reStructuredText format. Honestly, I still find the syntax a bit quirky, but the general utility of the whole workflow is high enough that I find those quirks can be overlooked. Your mileage may vary…

The reStructuredText source documentation is rendered into different target formats using the sphinx tool - pdf, html, latex & others. Rendering themes are often applied using additional pip installed packages, for example installing the package sphinx_rtd_theme & applying the theme in conf.py configuration will enable your documentation to be rendered to look like the “readthedocs” website.

ReStructuredText is more sophisticated than Markdown, but still less capable than a Word or LaTeX document. The important thing is that like Markdown, it is a human readable syntax. For those maintaining reStructuredText documentation, it’s easy to review, edit & have a sense of what the final product will look like without actually rendering the documents into any particular format.

Here’s two examples of the initial file hierarchy created by the sphinx-quickstart command, that are defined by slightly different choices in the quick start prompts.

# sphinx-quickstart file structure without separate source & build directories
docs/
├── Makefile
├── _build/
├── _static/
├── _templates/
├── conf.py
├── index.rst
└── make.bat

# sphinx-quickstart file structure *with* separate source & build directories
docs/
├── Makefile
├── build/
├── make.bat
└── source/
    ├── _static/
    ├── _templates/
    ├── conf.py
    └── index.rst

The important thing is to ensure that the empty directories _build , build , _static & _templates are pinned in your git repository by committing a .empty file in each directory. This is so that anyone subsequently cloning the repository automatically acquires the empty directories. Otherwise the build commands can fail due to the missing directories.

References

https://www.sphinx-doc.org/en/master/ - Sphinx documentation

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - ReStructuredText primer

https://docs.anaconda.com/restructuredtext/ - ReStructuredText cheatsheet

https://sphinx-rtd-theme.readthedocs.io/en/stable/installing.html - Sphinx RTD theme installation