Update to newer Sphinx version for building documentation

[rwest]

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.

[bryanwweber]

This would probably be a good idea in advance of 3.0. @chinahg and I have been working to use Sphinx for the website as well, with the pydata-sphinx-theme. I'm not sure what will need to be done on this side, but if you or your lab can put some hours to help out that'd be great!

[speth]

Here's an example of a few things that happen using the current version of Sphinx (6.2.1). Compare this to the same page in the dev docs.

First, the table of contents on the left is overflowing into the main content area, and is also including far more detail (every single member function/variable) than we really want.

---

---

Second, something is causing the horizontal rule that should separate every class member is not shown before `property` items, but is for other members:

---

---

@rwest, if you have the time to fix these issues and make sure all the other Sphinx output is being formatted correctly, I'd be happy to accept a pull request changing the version of Sphinx used to generate the documentation that is uploaded to cantera.org.

[rwest]

Thanks for the examples, Ray, that helps. We'll post here if/when we start work on it.

[rwest]

For what it's worth, Sphinx 5.1.1 & Alabaster 0.7.12 & sphinxcontrib-matlabdomain 0.18.0 (which my combination of conda/pip chose to install for me) seems to do an OK job:

I think @ssun30 is starting to look further into this.

[ssun30]

I pinned Sphinx version to 5.1.1 in the CI test and all tests passed. I'm also not getting formatting issues in the generated html files. So I think this could be a viable temporary workaround for now.

The underlying cause for bloated table of contents is caused by this enhancement request: sphinx-doc/sphinx#6316. The feature was then introduced in Sphinx 5.2.0 which defaults to create TOC entry for every class, funtion, and method. In Sphinx 5.2.3 a directive option :nocontentsentry: was introduced to prevent a class/function/method from being included in the TOC (see sphinx-doc/sphinx#10886).

However, as of Sphinx 7.0.0, that directive option is not included in sphinx.ext.autodoc and thus autodoc will default to create that very big TOC. It is a pretty simple change so I think I could open an issue and a PR to address this. This would require adding the :nocontentsentry: directive option for every class in the RST files so it would be a cumbersome job. Ideally we would want this to be a global option that the user could define in conf.py.

But so far, this is what I'm able to get on Sphinx>=5.2.3 and <7.0.0 with a proof-of-concept patch to Sphinx.

[speth]

Thanks for digging into this, @ssun30. Unless there are some new features / bug fixes that you specifically need from a version newer than 5.1.1, I'd say updating and pinning to that version would be a perfectly good solution for the time being.

I suspect that worrying about these specific formatting quirks for newer versions isn't worth it, with the prospect of switching to the pydata-sphinx-theme on the horizon as @bryanwweber mentioned.