- Generated by
1.13.2
|
|
Doxygen is used for documenting the C++ sources of the ArmarX Framework and its dependent programs.
Slice2Html is used for documenting the slice files.
The ArmarX documentation system works as easy as typing
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.
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/
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):
The HTML pages are generated into the .../build/doxygen/html directory. The main page of the documentation is located here:
You can open it with
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:
and open it with
The documentation is built from two main resources:
etc/doxygen/ directoryThe 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.
Doxygen collects files from various folders. To link to a page, the location of that file is irrelevant. Instead, each page needs to define its ID.
In .dox files, this is typically done using the \page command at the beginning of the file. Make sure to put the Doxygen content into a C++ documentation comment. Otherwise, the file will be treated as empty and will not appear in the generated documentation. Also, make sure NOT to use quotation marks around the name, even if it consists of multiple words. This is different to the use of the \ref command.
The ID does not have to follow a specific scheme. However, a widespread scheme is ${PROJECT_NAME}-name-as-multiple-words. Underscores (_) and hyphens (-) are admissible in IDs, but colons (:) are not. Now, you can link to this page anywhere using \ref ID "Text of the link". Here, the quotation marks are important, even if the text of the link is just a single word.
In .md files, defining the ID is typically done using an appendix to a level-one heading at the beginning of the file.
The structure of the documentation is reflected in the table of contents tree on the left hand side when viewing the HTML documentation. Bold font weight indicates individual pages, while normal font weight indicates sections of a page. The structure is defined by specific Doxygen commands:
If you use \defgroup in a .dox file, be aware that this needs to be the first command. Writing it after \page will lead to the page remaining blank.
Instead of \defgroup and \ingroup, and referring to pages via \ref, \subpage can be used. See the Doxygen documentation at https://www.doxygen.nl/manual/commands.html#cmdsubpage.
In case of errors, there usually is not an error message, but a fallback behavior. For example:
To prevent a link automatically being set by Doxygen at a certain location, prepend a % sign in front of the word. See the documentation at https://www.doxygen.nl/manual/faq.html#faq_class for details.
The toplevel structure looks like this (refer to the detailed package structure below for more information):
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.
Gui-Plugins
filename:
starts with:
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:
Class documentation starts with:
Todo:
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/latest/addons/doxygen.cmake
which is included by
ArmarXCore/etc/cmake/latest/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}
${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".
Images (and videos) are copied from "${PROJECT_ETC_DIR}/doxygen/images" to "images/" in the output directory. Be aware that only the following file types are copied: .png, .jpg, .svg, and .mp4. These types can be extended in ArmarXCore/etc/cmake/latest/addons/doxygen.cmake. When linking to these images, the path needs to be ../../images/[...]. However, this means images won't be visible in a markdown preview, but only in the file rendered by Doxygen.
Two custom targets are available for generating the documentation.
ArmarXCore/etc/cmake/Documentation.cmakeArmarXCore/etc/cmake/Documentation.cmakeThe 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
1.13.2