2.5. Documentation Meta¶
Documentation is generated with Doxygen and then fed to Sphinx via the Breathe extension. A custom C# domain sphinx-csharp is used to be able to render the C# code as well. By using the m2r sphinx extension markdown is converted to reStructuredText .rst
which is what sphinx expects. This allows us to write markdown with inline rst. rst directives are used to access the Doxygen documentation (see breathe).
Code is documented with xml-doc in C# and javadoc in C++ currently. Using Crl
+ Q
in JetBrains IDEs allows displaying the documentation quickly inline when developing.
Note
The markdown files are meant to give an overview, but most documentation should be in the code itself. The recommended cross-platform md/rst editor that I use is Typora, see https://typora.io
2.5.1. Modifying the Documentation¶
Annotate your code (e.g. functions, vars) with either xml-doc or javadoc
You can add a new md file but it must be referenced in a
toctree
directive (usually found inindex.*
). CMake must re-run when doing this.Ideally have a markdown file per source directory
Inline diagrams/flowcharts are made with diagrams.net (previously draw.io) and inserted as an iframe
These are stored on Google Drive
Gifs in the gallery are created with ScreenToGif
After making changes fast forward the read-the-docs
branch to the latest commit on the master branch. This will trigger read the docs to rebuild and update the online documentation.