Documentation
Introduction
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.
Local compilation
The output HTML files
reside in docs/build/
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).
First time:
cd docs
sphinx-build -b html source/ build/
Thereafter:
cd docs
make clean
make html
The make clean
is preferable not omitted
as doing so tends to lead to not updating files that should have been updated.
Compiling autodocs
In short,
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 docs/source/autodocs
.
cd docs
sphinx-apidoc -o ./source/autodoc ../src/fonsim -f
rm source/autodoc/modules.rst
rm source/autodoc/fonsim.rst
The files modules.rst
and fonsim.rst
are deleted
to avoid generating
‘WARNING: document isn’t included in any toctree’.
Updating ReadTheDocs
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.