Abstract

In conjunction with the website backend updates envisioned by Cantera/cantera-website#209, Cantera/cantera-website#210, and Cantera/cantera-website#211, I think it's time to reconsider the split of what content belongs as part of the cantera-website repository, and what belongs in the main cantera repository alongside the source code.

Motivation

Having spent some time on the website updates for Cantera 3.0 (see Cantera/cantera-website#248), I'm coming to the conclusion that a large portion of what is currently in the website repo actually belongs with the source. Given the norm of having the unversioned website content be applicable to the stable Cantera release, many of these updates are things where we don't really have a way to stage changes for the new release as it's being developed, like documenting changes to the build dependencies, deleting references to the now-removed CTI format, and documenting new models. And even when updates can be made in parallel, the additional work of putting together a second PR for the website is often delayed or never happens.

This strong separation between code and its documentation is also I think one of the causes for a significant backlog of updates where changes and new capabilities are not documented at all, outside the somewhat obscure API docs. Just as a starting point, here are ones where issues have been created:

• Add information on derivative calculation to science section cantera-website#169
• Electrochemical Reactions missing from Science Section cantera-website#172
• Update three-body reaction Science documentation cantera-website#216
• Mole-based reactors are undocumented cantera-website#244
• FlowReactor documentation needs to be updated cantera-website#247
• Eliminate Remaining Reaction Specializations when using MultiRate Evaluators #142
• Science section re-org #146
• Verify, catalog, and document Cantera ThermoPhase classes. #6 (the granddaddy of them all)

Description

Specific sections currently in the cantera-website repository that I think belong in the main code repository are:

• Installation instructions
• Programming tutorials
• Input file tutorials
• "Science" documentation

What this leaves for the cantera-website repository is pretty light:

• Home page
• Community
• Blog (mostly unused)
• structure to enable navigating all version-specific documentation

Using this organization, I think we should consider ourselves free to make documentation updates to the current stable branch and always use that branch to generate the active version of the website, even if we don't anticipate a future bugfix release.

I would say that my biggest question in all of this is how to go about implementing it, alongside @bryanwweber's suggested/planned changes to use a stack consisting of Sphinx / MyST / Pydata theme.