Generating Code Documentation for the VON Project

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.

TO DO: Additional work is needed for the generating JavaScript documentation using Sphinx. We’ll get to that.

Notes for Developers

Target Audience

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.

We are using the Napoleon Sphinx Extension to process the Google or NumPy docstrings style, and you can use any of the features from that extension as listed in the Napoleon documentation.

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 sphinx-apidoc command.

Overview Documentation

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 index.rst file.

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