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 https://github.com/Cantera/enhancements/issues/178#issuecomment-1644858874 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
[x] Update the main page ... Cantera/cantera#1516 / Cantera/cantera#1534
[x] Add treeview and fix links ... Cantera/cantera#1535 / Cantera/cantera#1543
[x] Switch Doxygen documentation theme / put details on top ... Cantera/cantera#1546
[x] Add bibliography ... Cantera/cantera#1550
[x] Add links to previous versions ... Cantera/cantera#1551
[x] Standardize command style (@ vs. \ commands; most instances use the former, but there are some instances of the latter as well) ... Cantera/cantera#1557 and Cantera/cantera#1558; also Cantera/cantera#1565
[x] Sort BibTeX file alphabetically to reduce likelihood of merge conflicts ... Cantera/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
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.
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 https://github.com/Cantera/enhancements/issues/178#issuecomment-1644858874 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
@vs.\commands; most instances use the former, but there are some instances of the latter as well) ... Cantera/cantera#1557 and Cantera/cantera#1558; also Cantera/cantera#1565Beyond, Doxygen documentation can be improved by increased use of
\defgroup/\addtogroup/\ingroupas 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
Alternatives
Use Sphinx +
breathe/exhaleor 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
115
145
178