The documentation of the FONSim project resides together with the code in the GitLab repository in the directory docs/source. This directory contains the documentation source files, written in reStructuredText (rST). All rST files in the directory autodoc are generated using tools while the other rST files, such as the one used to render this document, are compiled manually.
These reStructuredText files are rendered to HTML, viewable in a browser, using Sphinx. This HTML documentation is then hosted on the internet thanks to the ReadTheDocs organization. The ReadTheDocs servers look at the FONSim GitLab repository and more or less rebuilds the documentation every time the codebase on the GitLab repository changes.
The Sphinx + ReadTheDocs documentation has a nice “How To” guide. The FONSim project mostly adheres to the default choices.
The rest of this documents discusses how to build the documentation.
The output HTML files
and can be viewed in a web browser.
They closely resemble those that will be built by the ReadTheDocs server
(their process is slightly different though).
sphinx-build -b html source/ build/
make clean is preferable not omitted
as doing so tends to lead to not updating files that should have been updated.
the Sphinx autodocs functionality takes the codebase,
strips all the code away and dresses the docstrings
in nice rST files.
These rST files only contain references to the docstrings
and therefore not the docstrings themselves.
Therefore, it is not necessary to rerun the Sphinx autodocs
unless major changes to the code structure are made.
The generated autodocs reside in the directory
sphinx-apidoc -o ./source/autodoc ../src/fonsim -f
fonsim.rst are deleted
to avoid generating
‘WARNING: document isn’t included in any toctree’.
The ReadTheDocs server is configured to look at the GitLab repository and recompiles the documentation automatically. However, it will fail at the smallest error, so it is preferable to check the documentation source files first by doing a local compilation and observing the output.