DOC: Sphinx 5.2.0 broke doc build

[tylerjereddy]

New version of Sphinx (5.2.0) placed on PyPI about 5 hours ago, and I can reproduce the issue with a local doc build on our latest main. We're still "ok" with 5.1.1 as far as I can tell, so we could temporarily pin while we investigate.

Sample error log: https://app.circleci.com/pipelines/github/scipy/scipy/15646/workflows/40bc142d-50a5-4837-92ee-fa0790cca7f6/jobs/55158

Short summary of error:

<snip>
sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: :2: (SEVERE/4) Unexpected section title.

Compressed sparse graph routines (:mod:`scipy.sparse.csgraph`)
==============================================================

Sphinx parallel build error:
docutils.utils.SystemMessage: :2: (SEVERE/4) Unexpected section title.

Compressed sparse graph routines (:mod:`scipy.sparse.csgraph`)
==============================================================
make: *** [Makefile:110: html-build] Error 2

Exited with code exit status 1

If I do this (the overline should be optional I think):

diff --git a/scipy/sparse/csgraph/__init__.py b/scipy/sparse/csgraph/__init__.py
index df8f772ad..cf836e2c8 100644
--- a/scipy/sparse/csgraph/__init__.py
+++ b/scipy/sparse/csgraph/__init__.py
@@ -1,4 +1,5 @@
 r"""
+==============================================================
 Compressed sparse graph routines (:mod:`scipy.sparse.csgraph`)
 ==============================================================

the error changes only slightly:

<snip>
sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: :1: (SEVERE/4) Unexpected section title or transition.

==============================================================

Sphinx parallel build error:
docutils.utils.SystemMessage: :1: (SEVERE/4) Unexpected section title or transition.

[tylerjereddy]

If I delete the section marking (underline) entirely, Sphinx goes on to complain about another similarly-formatted section title:

sphinx.errors.SphinxParallelError: docutils.utils.SystemMessage: :2: (SEVERE/4) Unexpected section title.

Sparse linear algebra (:mod:`scipy.sparse.linalg`)
==================================================

If I delete that second one, Sphinx can get through the reading stage and start writing docs. Then we get heavy spam of this:

WARNING: generate_nav_html is deprecated and will be removed.Use generate_toctree_html instead.

Anyway, I'll likely leave this to our doc experts, just wanted to document in reasonable detail.

[WarrenWeckesser]

Then we get heavy spam of this:

WARNING: generate_nav_html is deprecated and will be removed.Use generate_toctree_html instead.

FYI: That warning is coming from the pydata_sphinx_theme: https://github.com/pydata/pydata-sphinx-theme/blob/39b6a7f34857d159aa0fddb707c436c01dc3355f/src/pydata_sphinx_theme/__init__.py#L357-L363

[tylerjereddy]

The doc build works just fine on latest main with sphinx at 5.3.0, but the original error still exists with 5.2.0.

We have explicitly blocked bad versions of sphinx before because i.e., git grep -E -i -n "sphinx!="

doc_requirements.txt:3:Sphinx!=4.1.0
pyproject.toml:89:    "sphinx!=4.1.0",

I suppose we could add 5.2.0 to that "block list", though I think we also have issues with newer Sphinx release major versions, if only because of other parts of the doc building dependency stack interacting with it. So, I'm not sure it would be sustainable to keep the version block list updated anyway, but overall we could probably just close this issue I suppose.