The Confluence Documentation you are looking at right now only serves the purpose of a "high-level" doc - it does provide you with code snippets, tutorials, troubleshooting etc., but it does not include detailed code-specific information. We decided to use Doxygen for that instead.
Most of our code should be documented properly using Doxygen commands. You only need to create the Doxygen page from the already existing Doxygen configuration file. The following sections tell you how to do that, and where to find that documentation.
Please install the Doxygen and Graphviz (for graphs drawn in Doxygen pages) packages, e.g. on Ubuntu:
apt install doxygen graphviz
The file output is set to
../doxygen, so maybe the folder must be generated first. If the software repository of this project is in
~/software, create a folder in
Creating your Documentation
We do not host our Doxygen documentation on a separate server. As it is very easy to generate the Doxygen sites yourself, you need to create them locally instead.
First, enter the directory of this project, which usually is
The doxygen_config file should be present in this folder. All you need to do is run the following command to create the doxygen output in the
../doxygen folder (relative from your current location):
As soon as the command has finished, head over to the doxygen folder:
There you can find different .html as well as other files. Just open
~/dev/doxygen/html/index.html in your browser to view and navigate through the generated documentation.
Some notes on settings in the Doxygen config file can be found below. All mentioned keywords have been used. For some, additional information on why you might want to change them are added.
INPUT (currently redundant, as ./ is given in the end; only ./LICENSE is relevant additionally, because else the file without ending would not be included due to the set file patterns)
EXTRACT_STATIC (set to YES)
For struct definitions with attribute in the low_level_controller, to recognize the struct name I had to enable:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)=
Set to yes:
Set EXTRACT_ALL to YES if you want undocumented files to appear in the documentation as well - currently: NO
USE_MDFILE_AS_MAINPAGE can also be used instead of the current DoxygenMainpage.hpp - currently: NO
EXCLUDE to exclude bcm2835.h, as it contains its own mainpage, as well as the catch.hpp/cpp files, and most .md files, and most package files
SORT_BRIEF_DOCS was set to YES by me - even though this also changes the class list, it is irritating to see functions in a group overview in a non-alphabetical order, so I changed that