Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Why Doxygen?

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. 

Prerequisites

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 ~/dev/software, create a folder in ~/dev/doxygen.

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 ~/dev/software:

cd ~/dev/software

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):

doxygen ./doxygen_config

Now all you need to do is head over to the doxygen folder

cd ../doxygen

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.

Settings

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)
RECURSIVE
FILE_PATTERNS
GENERATE_TREEVIEW
EXTRACT_STATIC (set to YES)

PROJECT_NAME
PROJECT_BRIEF
PROJECT_LOGO
OUTPUT_DIRECTORY

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:
EXTRACT_PRIVATE
EXTRACT_PRIV_VIRTUAL

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

  • No labels