Consolidate YAML API documentation in doxygen

[ischoegl]

Changes proposed in this pull request

This PR documents an attempt to consolidate Sphinx documentation for YAML Input within doxygen. The test emerged from discussion in Cantera/enhancements#178; the starting point was to test doxygen's capabilities for the integration of markdown files.

This PR consolidates the following information:

• YAML Format Reference from this repository (original reST files are removed)
• YAML Format Tutorial from Cantera/cantera-website
• doxygen generated pages are a drop-in replacement of current content
• updated documentation uses a doxygen flavor of markdown, which is presumably easy to port to MyST if so desired at a later point (MyST is a superset of markdown).

Other comments:

• Sphinx reST pages are ported using pandoc and manually edited (also: some content is reshuffled to take advantage of table-of-content browsing)
• Most cross-links are now handled by doxygen internally, where warnings are raised for broken links; it becomes trivially easy to link to C++ implementations (with corresponding docstrings)
• The approach is obviously applicable to content that is currently located in the Cantera/cantera-website repository (e.g. C++ examples/tutorials, compiling instructions, ...)
• Landing page is renamed to Cantera Developer API

If applicable, fill in the issue number this pull request is fixing

Partially addresses Cantera/enhancements#178 Partial fix for Cantera/cantera-website#250 (by avoiding links between doxygen and Sphinx generated content)

If applicable, provide an example illustrating new features this pull request is introducing

Rendered content:

Format Reference

Works for doxygen=1.9.1 and 1.9.2. There is a known treeview bug in 19.3 until 1.9.6; this appears to be fixed in 1.9.7 although subpage tables of contents do not render for 1.9.7, see bug report (marked as fixed, but not yet released). I retrieved all doxygen versions from conda-forge.

Checklist

• [x] The pull request includes a clear description of this code change
• [x] Commit messages have short titles and reference relevant issues
• [x] Build passes (scons build & scons test) and unit tests address code coverage
• [x] Style & formatting of contributed code follows contributing guidelines
• [x] The pull request is ready for review

[ischoegl]

Realizing that doxylink is actually set up (:ct:, not sure what took me so long 🎉 ), I created links from Sphinx: linking to sections defined in Doxygen markdown files works nicely, see:

[ischoegl]

Thanks for the feedback! I do agree that it is a substantial refactor, but strongly believe that merging YAML tutorial and reference makes for an improved user experience (having to look up pieces at two disjoint parts of the website is imho not ideal).

Whether consolidated YAML documentation goes into Doxygen (as proposed here) or Sphinx is probably not too consequential. For my own part, I believe Doxygen is slightly simpler, as cross references are handled internally, and tests only require running scons doxygen. Doxygen produces useful warnings about broken links by itself.

Regarding your comments:

• There currently is no good solution for YAML syntax highlighting in Doxygen, see https://github.com/doxygen/doxygen/issues/7551; it should, however, be possible using a preprocessing step. I am, however, not completely convinced that syntax highlighting adds much to YAML.
• Regarding versions: I checked and appear to accidentally have pulled content from an unmerged fork for the MyST refactoring effort, which explains the discrepancy.

[ischoegl]

This is largely superseded by #1572 and #1573. Regarding other items, I opened Cantera/enhancements#182.

One bit I spent some time on (and which I believe may be worth porting) was to update the documentation of the coverage-dependent species YAML documentation, which I found utterly confusing. Edit: opened #1579.