Use Doxygen effectively

[ischoegl]

Abstract

While Cantera has a long history of using Doxygen for docstrings, the generated website (and underlying organization) has not seen major updates for some time (little changed since Cantera 1.x). Based on a recent comment #178 (comment) it is expected that Doxygen-generated web content will retain some role for the foreseeable future.

Motivation

There is a large amount of quality documentation contained in Doxygen docstrings. Unfortunately, inadquate organization, as well as the location of details within generated html files, makes this information hard to find. As a result, it is quite hard to get an overview of the organization of the source code, which creates a steep learning curve for anyone wanting to contribute new features implemented in C++.

Compared to the alternative (recreate documentation in Sphinx), updating Doxygen is comparably simple and should be considered the 'low-hanging-fruit' for improvements to Cantera documentation.

Description

• Update the main page ... Improve main page of C++ documentation cantera#1516 / Update doxygen Chemical Kinetics/Numerics Documentation cantera#1534
• Add treeview and fix links ... Missing doxygen groupings cantera#1535 / Update doxygen (cont'd) cantera#1543
• Switch Doxygen documentation theme / put details on top ... Switch doxygen documentation theme cantera#1546
• Add bibliography ... Use Doxygen @cite cantera#1550
• Add links to previous versions ... Provide links to previous Doxygen documentation cantera#1551
• Standardize command style (@ vs. \ commands; most instances use the former, but there are some instances of the latter as well) ... Doxygen formatting cantera#1557 and [docs] Differentiate Doxygen from LaTeX commands cantera#1558; also Standardize code cantera#1565
• Fix remaining warnings ... Fix Doxygen warnings cantera#1559
• Ensure that autobrief works as intended ... Doxygen autobrief does not work for /*! cantera#1560 / Doxygen autobrief fixes cantera#1561
• Update Doxygen style guide ... Update Doxygen style instructions cantera#1562
• Sort BibTeX file alphabetically to reduce likelihood of merge conflicts ... Doxygen cleanup cantera#1567

Beyond, Doxygen documentation can be improved by increased use of \defgroup / \addtogroup / \ingroup as well as effective use of Doxygen markdown in docstrings and files (which replaces *.dox).

In addition, it is possible to move advanced content to Doxygen

• Consolidate YAML documentation ... Consolidate YAML API documentation in doxygen cantera#1548
• Move additional 'advanced' content from Sphinx as a long-term goal (?)

Alternatives

Use Sphinx + breathe/exhale or similar to render Doxygen XML content.

There is no question about Sphinx being the main tool of choice for the creation of user-facing web content. At the same time, it does not appear to be a good use of time to make C++ documentation accessible from Sphinx: Doxygen by itself has powerful - albeit currently underused - features, and Doxygen content can be easily cross-referenced by Sphinx using sphinxcontrib-doxylink. Maintaining a secondary 'Cantera Developer API' website - as has been done since at least Cantera 2.x - is a solution that requires minimal developer resources.

References

• Improve visual consistency and linking between Doxygen/Sphinx docs #115
• Consolidate works cited #145
• Reorganize website source material to simplify updating #178