Documentation

Table of Contents

Doxygen is used for documenting the C++ sources of the ArmarX Framework and its dependent programs.

Slice2Html is used for documenting the slice files.

Documentation Setup

The ArmarX documentation system works as easy as typing

make doc

in the build directory of your project of interest All necessary files and directories are automatically generated by CMake. For detailed information about the documentation system see Internals of the Documentation system.

Additional documentation, images, code snippets can be added by the user in designated directories. Take a look at the Conventions used for documentation to see where everything must be located and how pages and sections should be named.

Generating Documentation

The documentation is automatically generated by our GitLab CI/CD pipeline of ArmarX Documentation and is available under the following URL:

https://armarx.humanoids.kit.edu/

Single ArmarX Package

To generate the documentation yourself locally, you can use the following commands, replacing ArmarXCore with the name of your package of interest:

Build the source documentation (includes the Slice documentation):

cd $ArmarXCore_DIR # cd .../ArmarXCore/build/
make doc

The HTML pages are generated into the .../build/doxygen/html directory. The main page of the documentation is located here:

.../ArmarXCore/build/doxygen/html/index.html

You can open it with

xdg-open $ArmarXCore_DIR/doxygen/html/index.html

All ArmarX Packages (like Online Documentation)

The online documentation at https://armarx.humanoids.kit.edu/ is generated by the ArmarX package ArmarX Documentation (technically known as armarx_documentation). It merges the documentation of all (considered) ArmarX packages into one, which allows cross-referencing documentation pages and source code across packages.

Just as with single packages, you can generate the documentation via make doc in the build directory:

cd $armarx_documentation_DIR
make doc

and open it with

xdg-open $armarx_documentation_DIR/doxygen/html/index.html

Structure of Documentation Files

The documentation is built from two main resources:

  • In-code documentation in the source code
  • Documentation files in the etc/doxygen/ directory

The out-of-source documentation files usually generate separate pages (such as this one). They can be written in Doxygen (.dox) or Markdown (.md) (see Doxygen's Markdown Support). Even in Markdown files, virtually any Doxygen command can be used.

Note
PyCharm (the Python IDE by JetBrains) is also great for editing Markdown. It provides a side-by-side preview, which also supports images. In addition, it has some ´refactoring capabilities which is useful when renaming directories, for example. However, it (currently as of writing this) does not support the specials of Doxygen in Markdown as well as the ArmarX documentation setup (e.g., resolving references or links to images in the images directory). Still, it can tremendously support you in writing Markdown (especially formatting text, tables, etc.).

The structure of the table of contents (left hand side when viewing the HTML documentation) is defined by specific Doxygen commands:

  • All pages without \addtogroup, \defgroup or \ingroup will appear as toplevel entries
  • \defgroup or \addtogroup will open a new entry in Modules/Documentation
  • -> nesting happens when \ingroup is used and the label is already present under the Modules group
  • Each package: mainpage.dox -> \ref ${PROJECT_NAME} "${PROJECT_NAME} Overview"

The toplevel structure looks like this (refer to the detailed package structure below for more information):

  • armarx_documentation
    • Overview (defined in armarx_documentation project)
      • List of $PackageName-Overview pages
    • Installation (\page in armarx_documentation; auto-generated containing \subpage with $PackageName-Installation)
      • List of $PackageName-Installation pages
    • Tutorials (\page in armarx_documentation; auto-generated containing \subpage with $PackageName-Tutorials)
      • List of $PackageName-Tutorials pages
    • HowTos (\page in armarx_documentation; auto-generated containing \subpage with $PackageName-HowTos)
      • List of $PackageName-HowTos pages
    • FAQ (\page in armarx_documentation; auto-generated containing \subpage with $PackageName-FAQ)
      • List of $PackageName-FAQ pages
    • Components/API Documentation
    • Gui Plugins
    • Slice Documentation (generated by armarx_documentation project)
    • Data Structures/API (main API documentation generated by Doxygen and sorted by namespaces)
    • About
    • License

Detailed package documentation structure (files are located in ${PACKAGE_NAME}/etc/doxygen/pages/). Each file must start with the code snippet shown below its entry.

  • Mainpage
    $PACKAGE_NAME/etc/doxygen/mainpage.dox
    Contents:
    \mainpage
    $PACKAGE_NAME description
    \li \subpage $PACKAGE_NAME-Overview "$PACKAGE_NAME Overview"
    \li \subpage $PACKAGE_NAME-Installation "$PACKAGE_NAME Installation"
    \li \subpage $PACKAGE_NAME-Tutorials "A$PACKAGE_NAME Tutorials"
    \li \subpage $PACKAGE_NAME-HowTos "$PACKAGE_NAME Howtos"
    \li \subpage $PACKAGE_NAME-FAQ "$PACKAGE_NAME FAQ"
    \li \subpage $PACKAGE_NAME-Components "$PACKAGE_NAME Components"
    \li \subpage $PACKAGE_NAME-GuiPlugins "$PACKAGE_NAME Gui Plugins"
    \li \subpage $PACKAGE_NAME-About "$PACKAGE_NAME About"
    \li \subpage $PACKAGE_NAME-License "$PACKAGE_NAME License"
    • Package Overview
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/Overview.dox
      starts with:
      \page ${PACKAGE_NAME}-Overview ${PACKAGE_NAME} Overview
      contains: description describing the overall package and its content on a higher level.
    • Installation (optional)
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/Installation.dox
      starts with:
      \page ${PACKAGE_NAME}-Installation ${PACKAGE_NAME} Installation
      contains: installation instructions for the package (library dependencies, special build commands, ...)
    • Tutorials
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/Tutorials.dox
      starts with:
      \page ${PACKAGE_NAME}-Tutorials ${PACKAGE_NAME} Tutorials
      contains: \subpage references to tutorials (each tutorial should be added as a separate file)
      • Single tutorial
        filename:
        $PACKAGE_NAME/etc/doxygen/pages/Tutorials-${brief description}.dox
        starts with (use a more meaningful short name instead of xyz):
        \page ${PACKAGE_NAME}-Tutorials-xyz XYZ Tutorial
        Note
        prefix each label/name of \section or \subsection with ${PACKAGE_NAME}-Tutorials-xyz-
        tutorial pages can optionally be put into a separate 'tutorials' subdirectory
    • HowTos
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/HowTos.dox
      starts with:
      \page ${PACKAGE_NAME}-HowTos ${PACKAGE_NAME} HowTos
      contains: HowTos (each howto can either be specified in this file or in a separate file)
      • HowTo included in HowTos.dox
        starts with (use a more meaningful short name instead of xyz):
        \section ${PACKAGE_NAME}-HowTos-xyz XYZ HowTo
        Note
        prefix each label/name of \section or \subsection with ${PACKAGE_NAME}-HowTos-xyz-
      • Separate Page HowTo
        filename (only when in separate file):
        $PACKAGE_NAME/etc/doxygen/pages/HowTos-${brief description}.dox
        starts with (use a more meaningful short name instead of xyz):
        \page ${PACKAGE_NAME}-HowTos-xyz XYZ HowTo
        Include in HowTos.dox as
        \subpage ${PACKAGE_NAME}-HowTos-xyz XYZ HowTo
        Note
        prefix each label/name of \section or \subsection with ${PACKAGE_NAME}-HowTos-xyz-
    • FAQ
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/FAQ.dox
      starts with:
      \page ${PACKAGE_NAME}-FAQ ${PACKAGE_NAME} FAQ
      contains: Frequently Asked Questions (each FAQ entry can either be specified in this file or in a separate file)
      • Single FAQ entry
        Note
        prefix each label/name of \section or \subsection with ${PACKAGE_NAME}-FAQ-xyz- starts with (use a more meaningful short name instead of xyz):
        \section ${PACKAGE_NAME}-FAQ-xyz How do I do XYZ ?
        Using the following filename if you put the entry in a separate file:
        $PACKAGE_NAME/etc/doxygen/pages/FAQ-${brief description}.dox
        starts with (use a more meaningful short name instead of xyz):
        \page ${PACKAGE_NAME}-FAQ-xyz How do I do XYZ ?
        Include in FAQ.dox as
        \subpage ${PACKAGE_NAME}-FAQ-xyz How do I do XYZ ?
    • Components/Applications
      filename:
      $PACKAGE_NAME/etc/doxygen/pages/Components.dox
      starts with:
      \addtogroup Components Components
      \defgroup ${PACKAGE_NAME}-Components ${PACKAGE_NAME} Components
      \ingroup ${PACKAGE_NAME} Components

    • Gui-Plugins
      filename:

      $PACKAGE_NAME/etc/doxygen/pages/GuiPlugins.dox

      starts with:

      \page ${PACKAGE_NAME}-GuiPlugins GUI Plugins
      The following Gui Plugins are available:
      \subpage ${PACKAGE_NAME}-GuiPlugins-${WidgetName1} ${WidgetName1}
      \subpage ${PACKAGE_NAME}-GuiPlugins-${WidgetName2} ${WidgetName2}
      \subpage ${PACKAGE_NAME}-GuiPlugins-${WidgetName3} ${WidgetName3}
      ...

      The subpage tags link to descriptions of the available widgets and must be added manually after defining the pages as follows.

      The main description of a Widget goes into the respective WidgetController header file (each GuiPlugin contains one or more Controller which represent the widget) filename:

      ${PACKAGE_DIR}/source/$PACKAGE_NAME}/gui-plugins/${PluginName}/*WidgetController.h

      Class documentation starts with:

      /**
      \page ${PACKAGE_NAME}-GuiPlugins-${WidgetName} ${WidgetName}
      here comes a description of the widgets functionallity from a user perspective
      add a nice screenshot with \image html widgetname-screenshot.png "screenshot of widget ..."
      */
      /**
      * \class *WidgetController
      */
      Note
      ${WidgetName} and ${PluginName} might be the same if the plugin contains only one widget.
    • Statecharts
    • Units
    • Observers

Todo:

  • ComponentProperties

Internals of the Documentation system

This section is only relevant for people trying to understand how the documentation system works.

The main magic happens in the following CMake script: 

ArmarXCore/etc/cmake/Documentation.cmake

which is included by 

ArmarXCore/etc/cmake/setup.cmake

First of all the script tries to find the doxygen binary. Without it a warning will get issued on the commandline.

Afterward, the following template files are copied to ${DOXYGEN_DOCUMENTATION_DIR}

and the following template files are copied to ${DOXYGEN_DOCUMENTATION_LAYOUT_DIR}

  • layout/Doxygen.css
  • layout/DoxygenLayout.xml
  • layout/Header.html
  • layout/Footer.hmtl

${DOXYGEN_DOCUMENTATION_DIR} is defined in 

ArmarXCore/etc/cmake/SetupDirs.cmake

as ${PROJECT_BINARY_DIR}/doxygen.

Additionally, the file "${ArmarXCore_TEMPLATES_DIR}/cmake/PropertiesDocumentation.cmake.in" gets copied to "${DOXYGEN_DOCUMENTATION_DIR}/PropertiesDocumentation.cmake".

Running make doc

Two custom targets are available for generating the documentation.

  • slicedoc (defined in ArmarXCore/etc/cmake/Documentation.cmake
  • doc (defined in ArmarXCore/etc/cmake/Documentation.cmake

The doc target is always available. If Doxygen was not found an error message will be displayed upon running make doc. The slicedoc target is only available if an interface library is getting built and if the doc target is registered as a dependency. This means that a call to 'make doc' will automatically build the Slice documentation, too.

After the Slice documentation has been built the next step is to execute the '${PROJECT_BINARY_DIR}/PropertiesDocumentation.cmake' file. This executes each component found in 'build/bin' to generate their property documentation.

Doxygen is invoked afterwards with ${DOXYGEN_DOCUMENTATION_DIR}/${PROJECT_NAME}.Doxyfile.

The output directory of the html documentation is defined as '${DOXYGEN_DOCUMENTATION_DIR}/${PROJECT_DOCUMENTATION_HTML_OUTPUT_DIR_REL}'. Both variables are defined in

ArmarXCore/etc/cmake/SetupDirs.cmake