Writing documentation

Documentation can be written in Markdown or reStructuredText (reST).

Use restructured text when more advanced featured are required, for example inserting a table of contents.

Add new documentation files to doc/index.rst.

Markdown

Use .md file name extension. Parsing is done with the Commonmark specification, see https://commonmark.org/

Restructured text

Use .rst file name extension. For details on the syntax, see https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

Installing documentation toolchain

Install Sphinx by running this in the doc subdirectory:

doc$ sudo apt install python3-pip
doc$ pip3 install -r doc_requirements.txt

Build documentation:

doc$ make html
doc$ make pdf

Run checks:

doc$ make spelling
doc$ make linkcheck