Python Documentation Using Sphinx
Documentation is undoubtedly a key component to a successful project, in addition to the actual useful code. I have been knowing Sphinx for Python documentation for a while. However, since I don’t have any knowledge in reStructuredText which Sphinx heavily relies on and there is no beginner’s tutorial that is really close to a real Python project, my attempt to learn Sphinx had not been very successful. Instead, I had been using Markdown for documenting projects. It turns out that Markdown is OK for a simple README or some simple usages of the project. When the project becomes heavy and huge, such as when developing a library, systematic and automatic documentation becomes necessary.
There are quite a few tutorial blogs or videos on Sphinx that could be found using Google. Usually the blogs and the videos are very short and the authors claimed that the readers or watchers should be able to use Sphinx in their own projects after reading or watching. This is not entirely true in practice. In those tutorials, there are missing logical connections between the kind of documentation we wanted to create and how we are going to create it. The concrete examples in those tutorials are nowhere close to a real Python library project. So those tutorials did not really helped me in studying Sphinx.
Recently, I watched Brandon Rhodes’s Sphinx tutorial session at PyCon 2013 by chance on YouTube. Although Brandon talked too much and it took almost three hours for the tutorial session, I found the concrete example he provided, the introduction to reStructuredText, the motivations and logical connections, and the hands-on Sphinx experiences are somethings that I was looking for. After watching the tutorial session and doing some offline practice, I am now able to create good documentation using Sphinx for my Python projects.
In this blog post, I am going to make some notes or updates on Brandon’s tutorial. Note that the Sphinx beginners should always watch Brandon’s long tutorial in the first place, and this blog post could by no means replace Brandon’s tutorial.
Brandon has created a simple
trianglelib library specifically for his Sphinx tutorial. The library and the accompanying Sphinx tutorial were created using Python 2 and Sphinx 1.x. To make the library and Sphinx tutorial compatible for Python 3 and the latest Sphinx 3.x, I modified Brandon’s code a little bit. In addition, I have also moved the API documentations entirely to the Python scripts, restructured the project directory layout, and taken better advantage of the latest
autodoc extension in Sphinx.
Previously, during the project development, I usually only put some brief comments in the Python functions or methods. However, since Python is not a strictly typing programming language, and those comments would not usually contain the typing information, I would hardly remember how those variables could be used.
In addition, creating a documentation after the entire project is done is an approach that I know it is wrong but I have been doing. It is low-efficiency and often error-prone. The correct approach should be documenting while programming. Since Sphinx could automatically generate documentations for all the modules, classes, and functions that follow its supported
docstring format, we are encouraged to document the Python program more comprehensively. Tools, such as Python Docstring Generator for VS Code could automatically generate the template for
docstring to save our time in documentation.
A well-documented Python program that is Sphinx-compatible looks like this.
Sphinx allows running some simple tests on the programs we created via
doctest. So sometimes writing some test code snippets in the reStructuredText not only helps documentation but also helps program validation.
The test code could be something like the followings.
from trianglelib.shape import Triangle
We could publish the documentations to our projects on Read the Docs for free. Read the Docs also allows us to do version control for our projects and documentations by creating
branch to our GitHub projects. It is extremely useful for the users who are not using the latest version of the software.
Learning Sphinx is not easy and I think there is no 15-minute shortcut for beginners. Instead of randomly Googling and reading superficial blogs and videos, spending two to three hours on studying Brandon Rhodes’s Sphinx tutorial session at PyCon 2013 actually saves time.
Python Documentation Using Sphinx