Doxygen

Introduction

In the machines-in-motion group we use doxygen in order to build all documentations from C/C++ and Python code. The main idea is that we can have a unified way to generate the documentation.

Usage

In order to use this macro one obviously needs to depend on this package through a find_package. Once the dependency is found ONE of the following macro needs to be added to the CMakelists.txt:

# to build the doxygen html
add_sphinx_documentation()
# to build the sphinx html
add_doxygen_documentation()
# to build both
add_documentation()

These macro are idle by default. To activate it one need to pass the following CMake argument:

colcon build --ament-cmake-args -DGENERATE_DOCUMENTATION=ON

The macro will generate a specific target using the name of the project for unicity. The documentations are located in:

workspace/install/<project name>/share/docs/doxygen/html/
workspace/install/<project name>/share/docs/sphinx/html/

In order to visualise the built documentation with firefox please run:

firefox workspace/install/<project name>/share/docs/doxygen/html/index.html

Writing a documentation

In order to write a decent documentation one need to make sure that Doxygen do not output warnings. A warning from DOxygen proves that a code item is not documentated. See the C++ coding guidelines , the Python coding guidelines and the General coding guidelines For more information on how our code style and the good code practice.

The documentation of your code is combined with several main items:

• First, one need to add the docstring of the language.

• Second, one need to provide unittests, these usually are good basis for an external user to understand the API.

• Third, one need to provide demos of the API defining the usual use case of the code. These code must contain doc-strings containing the key word, e.g. with C/C++:

  /** 
    * @example <file name> This example provide an example on how to use ...
    * Remarque: remove the `\` before the `@`.
    */
  

• Finally whenever you feel like documenting more extensively something and adding graph, image, extensive text explanation, link, etc, it is way more convenient to use markdown. Therefore one need to provide a doc/ folder containing the additional documentation.

For more detail on how to use doxygen here is a list of extremely useful links:

• List of doxygen commands

• Doxygen markdown support

Implementation details

The Doxyfile.in place in this repository’s resources folder is responsible for the parsing parameters and shape of the documentation. The idea here is that upon build Doxygen will go recursively through all the current project files looking for the C/C++/Python/Markdown files and generate the documentation automatically.

The subtility about python is that we use the doxypypy package in order to convert the Google docstring in the python code into Doxygen recognizable docstrings. So one need to install this dependency using pip for example.