Use Doxygen effectively #179
Description
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