Abstract

Could we update to a new version of Sphinx to build the documentation?

Motivation

Describe the need for the proposed change:

• in commit Cantera/cantera@d950681 2+ years ago @bryanwweber pinned the Sphinx version to <4.0 in the CI runs used to automatically build the documentation, noting "Sphinx 4.0 (from the main branch) is incompatible with several extensions we use (katex, matlabdomain)."

• in comment Matlab toolbox revamp cantera#1182 (comment) while working on the MATLAB toolbox re-write @ssun30 observed that sphinxcontrib-matlabdomain before a certain version was incompatible with a recent pygments and things worked better with sphinxcontrib-matlabdomain >=0.15.0, but that in turn needed a newer Sphinx.

• in comment Matlab toolbox revamp cantera#1182 (comment) @speth noted "Yes, there are reasons that we're pinning the doc build to an older version of Sphinx for now. Some of our templates don't work well with the most recent Sphinx releases, and currently lead to some ugly HTML output, which you'll see if you build locally with a current Sphinx release."

So it sounds like the original problem of new sphinx being incompatible with matlabdomain is now untrue (indeed a new sphinx would help). So the question is what else is holding Sphinx back, and can we fix it?

Possible Solutions

Maybe we could fix whatever remaining problems there are with templates so that we're compatible with a new Sphinx.
Does anyone recall what the issues are? Or suggest a good way to detect them? Other thoughts?

References

As well as the links above,
Enhancement #115 discusses visual consistency of sphinx documentation.