The VON Project uses Sphinx to generate technical documentation from code. Sphinx is the tool used to generate ReadTheDocs-style documentation and we’ve configured Sphinx to generate the documentation locally and from github in that format. We have not yet decided if we are going to server the generated documentation locally on the BC Gov OpenShift platform, or use ReadTheDocs.
Documentation Generation Setup
The current process for generating documentation is to use the Docker image cloudcompass/docker-rtdsphinx. The readme file on the docker image has most of the documentation necessary for setting up the generation for Python code. The github repo with the dockerfile, documentation and associated utilities for the Docker image can be found here.
Notes for Developers
The primary target audience for the generated documentation should be clients of the software in the repo. The “what is” and “how to use” focus of the overview documentation should reflect that target audience. Generated API documentation should focus on the public methods to be used by client software.
While documentation should also be created for those that wish to contribute to the repo, such developers are not the primary target.
The rtdgen Shell Script
We recommend that developers put the bin/rtdgen shell script into a directory on their path to simplify the process of locally generating the documentation. Some suggestions on how to do that are in the github/docker hub Readme file. Once that is done, most of the commands related to documentation generation can be run using that shell script.
Python Style: Use Google Style
Please use the Google Style for Python docstrings to document your new code. Existing code can remain as is, provided it generates useful documentation. If you have to fix existing docstrings, please convert them to Google Style.
Not Checking In Generated Documentation
As of now, generated documentation should not be checked into github. Please add
docs/build/ to the repo’s
.gitignore file if you are adding generated documentation to your project. We may change this in the future, but for now we’ll generate the “to be published” documentation at build time.
Pre-Commit Documentation Generation Checking
Developers should generate and review the documentation prior to commits where changes have been made to the docstrings.
Updating/Regenerating Package Lists
Sphinx maintains a list of the Python files to be included in the documentation. An initial list is created using the
sphinx-apidoc command (documentation). As the files that make up a Python package change, please update the or regenerate the file initially generated by the
It is a requirement that each code repo in the VON Project have a useful overview about what the code is for and how it is to be used as a preface to the generated code documentation.
The overview documentation must be added as markdown (md) or ReStructuredText (rst) files in the
docs/source folder and referenced in the Sphinx
Being DRY - but not too DRY
While we strife to be DRY, the repo Readme should include an extract of the “what for and how to use” overview documentation, along with links to the generated documentation. There should be little repeating of documentation, and a developer must be able to easily navigate to the “what is this” documentation regardless of how they navigate to the repo:
- from the readme in the github repo
- from the “ReadTheDocs”-style documentation
- from the “Getting Started” section of this site