Description

Doxygen documentation

Generation of the reference documentation of BmnRoot with Doxygen: all classes, functions and macros of the C++ code and ROOT macros with their inheritance, collaboration, include, call and caller graphs, the browsable source code, the README.md files of the directories as the module pages, and the BmnRoot Start Guide, the DIGI and DST format descriptions and the code documentation rules as the Related Pages.

The documentation of the dev branch is published on the GitLab Pages of the project: http://nica.pages.jinr.ru/bmnroot/

Building the documentation locally

Doxygen 1.10 or newer (the documentation is tested with 1.17) and Graphviz dot are required. The documentation is enabled by the BUILD_DOXYGEN CMake option and generated by the DoxygenDoc target:

source ~/bmnroot/SetEnv.sh
cmake -S ~/bmnroot -B ~/bmnroot/build -DBUILD_DOXYGEN=ON
make -C ~/bmnroot/build DoxygenDoc

The HTML pages are written to build/services/doxygen/doc/html (start page index.html), and the Doxygen warnings to build/services/doxygen/doxygen_warnings.log. Generation takes several minutes and about 1 GB of disk space, mostly for the graphs; the DoxygenDoc target is not a part of the default build.

At the configuration step, CMake downloads to the build directory:

the doxygen-awesome-css theme (version set by the DOXYGEN_AWESOME_VERSION variable); a local copy can be given with -DDOXYGEN_AWESOME_DIR=<path>;
the ROOT tag file of the used ROOT version (e.g. https://root.cern/doc/v636/ROOT.tag.gz), so the ROOT classes are linked to the ROOT reference guide; the global classes of the ROOT tests and tutorials (Event, Track, ...) and the global functions and variables of the ROOT sources and tutorials (h, x, name, ...) are removed from it, so that the common words and the local variables of the BmnRoot code are not linked to them.

Without network access, the documentation is built with the default Doxygen style and without the ROOT links. Another Doxygen executable can be selected with -DDOXYGEN_EXECUTABLE=<path>.

Publication

The pages job of .gitlab-ci.yml builds the documentation for every commit to the dev branch and publishes it on GitLab Pages. The job runs on AlmaLinux 9: Doxygen is taken from CVMFS, its environment is set by cluster_config.sh of the platform in the global before_script, as for the other jobs. The Doxygen warnings are kept as the doxygen_warnings.log artifact of the job.

The BmnRoot.tag file of the published documentation allows other Doxygen projects (e.g. analysis packages) to link to the BmnRoot classes: TAGFILES = BmnRoot.tag=http://nica.pages.jinr.ru/bmnroot/.

Writing the documentation

The rules for documenting the code, the macros and the directories are given in documentation_rules.md, which is also a page of the documentation (Related Pages).

The Related Pages are listed on the page related_pages, written by doc_makeall.sh.in: the documents generated by services/format_docs (Start Guide, DIGI and DST formats) in the order of DOCUMENTS, followed by the documentation rules. Another Markdown file of the source tree (not README.md) becomes a page with its file name as the label (added by md_filter.sh); add it to related_pages in doc_makeall.sh.in, otherwise it is a separate item of the navigation tree.

Files

File	Description
CMakeLists.txt	Downloads the theme and the ROOT tag file, configures doxyfile.in and doc_makeall.sh.in, adds the DoxygenDoc target
doxyfile.in	Doxygen configuration (only the options differing from the defaults, with comments)
DoxygenLayout.xml	Layout of the pages: the default one of Doxygen 1.17 with the description first on the directory pages
filter_root_tag.py	Removes the classes of the ROOT tests and tutorials and the files outside the public ROOT headers with their global symbols from the ROOT tag file (run by CMakeLists.txt)
documentation_rules.md	Rules for documenting the code, the macros and the directories of BmnRoot (a page of the Related Pages)
topics.dox	Topics of the documentation: thematic groups of the directories
md_filter.sh	Filter of the Markdown files for Doxygen: removes the GitLab-only text, turns the links to the source files into references to their pages, makes the README titles the brief descriptions of the directories, sets the file names as the labels of the other Markdown pages
open_diagrams.js	Opens the inheritance, collaboration, include and directory diagrams of a page when it is loaded; the call graphs and the large diagrams (shown in a zoomable frame, slow to draw) stay collapsed
doc_makeall.sh.in	Script run by the DoxygenDoc target: writes the page footer with open_diagrams.js, generates the Related Pages from services/format_docs, runs Doxygen, runs it a second time for the collaboration diagrams of the direct relations, corrects the links to the file-local symbols, reports the directories missing in topics.dox, removes the auxiliary graph files, reports empty pages of unresolved types to the warning log
fix_file_local_links.py	Corrects the links to the global variables, macros and types of the source files (e.g. the variables x and pMedAir of the geometry macros), which Doxygen makes from the same names in all files: they are changed to the symbols of the own file or removed
replace_collaboration_graphs.py	Puts the collaboration diagrams of the direct relations to the BmnRoot and ROOT classes (second Doxygen run with MAX_DOT_GRAPH_DEPTH = 1, HIDE_UNDOC_RELATIONS = YES) in place of the full ones, which have hundreds of nodes for many classes

Directory dependency graph for doxygen: