Sphinx

Sphinx is a documentation generation tool originally created for the generating the Python language documentation.

External Documentation

Installation Notes

Before proceeding, make sure that you have created and activated the codecraftsmen virtual Python environment as described here.

Sphinx can be installed using pip like this:

workon codecraftsmen
pip install sphinx
pip install sphinx-rtd-theme

Some of the Code Craftsmen projects also use the sphinx_autodoc_typehints Sphinx extension to format Python API documentation. This extension can also be installed using pip:

pip install sphinx_autodoc_typehints

Our C++ projects use Doxygen to extract API documentation from C++ source files and the breathe Sphinx extension to integrate and format that documentation using Sphinx. These tools can be installed by running the following commands on Ubuntu 20.04/18.04:

sudo apt-get install doxygen
pip install breathe

Our C projects use the kernel-doc Sphinx extension to extract API documentation from C source files and integrate the results into Sphinx. This extension is typically distributed as part of the Linux kernel source tree, so we simplify the distribution and installation process by including a copy of the required files under the doc directory of the projects that require this extension.

Performing the steps listed above should be sufficient for building the HTML documentation for most, if not all, Code Craftsmen projects. If you want to build PDF output, you will need to install these additional packages on Ubuntu 20.04/18.04:

sudo apt-get install latexmk texlive-latex-extra texlive-latex-recommended

Extra Setup for Projects Using Read the Docs

For Python projects that require prerequisite pip packages to build the documentation, a requirements.txt file needs to be added to the project’s documentation directory to allow the build to succeed on the Read the Docs site.

Extracting Embedded Documentation from Python Code

Extracting Embedded Documentation from C++ Code

  • Documentation for the Doxygen C++ documentation generator

  • Documentation for the breathe extension (integrates Doxygen output with Sphinx)

  • Documentation for the Sphinx C++ domain

  • See the Cuddl project’s doc directory for an example of how to set up Sphinx for C++ API documentation.

Extracting Embedded Documentation from C Code

  • Documentation for the kernel-doc extension

  • Documentation for the Sphinx C domain

  • See the Cuddl project’s doc directory for an example of how to set up Sphinx for C API documentation.

Miscellaneous Notes