Doctests failures with Sphinx 8.2.0

[lbianchi-lbl]

• The doctests started failing at some point in the last day
• This seems to be connected with Sphinx 8.2.0 as Pin Sphinx to not 8.2.0 Pyomo/pyomo#3479 and Temporarily exclude sphinx 8.2.0 to fix doctests #1572 resolve the failures
• Even with this effective workaround, we think it's worth to look into the failures as they are "interesting" and could point to a legitimate issue (in the code snippets, doctests infrastructure, library code, etc) that we might be able to address

---

[lbianchi-lbl]

Running git bisect on sphinx-doc/sphinx between the tags v8.1.3 (✅ ) and v8.2.0 (❌) points to sphinx-doc/sphinx@e17ed74 being the commit that introduced the breaking change:

$ git bisect run bash -c "cd ../idaes-pse/docs && sphinx-build -M doctest . _build"
e17ed74fe027eb84aaf72ce92c4b1bd8ebf8c049 is the first bad commit
commit e17ed74fe027eb84aaf72ce92c4b1bd8ebf8c049
Author: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date:   Sat Jan 4 06:36:34 2025 +0000

    Remove unneeded content from within ``with`` statements

 sphinx/builders/changes.py               | 13 +++++-----
 sphinx/builders/gettext.py               | 16 ++++++------
 sphinx/directives/code.py                |  6 ++---
 sphinx/ext/autosummary/generate.py       |  2 +-
 sphinx/ext/imgmath.py                    |  3 ++-
 sphinx/util/docutils.py                  |  7 ++---
 sphinx/util/osutil.py                    |  4 +--
 tests/test_builders/test_build_latex.py  |  2 +-
 tests/test_extensions/test_ext_apidoc.py | 44 ++++++++++++++++----------------
 utils/babel_runner.py                    | 11 ++++----
 10 files changed, 56 insertions(+), 52 deletions(-)
bisect run success

EDIT after reviewing the changes, it looks like most of them are (almost) non-functional and unlikely to have an effect. I tried checking out that commit and re-running the "probe" command, which didn't fail, so most likely something was off with git blame.

EDIT 2 re-running git blame points to a commit that looks more relevant (sphinx-doc/sphinx@fec4d7c):

fec4d7c2f1f741374b3a6bba16960ab232a8f3dd is the first bad commit
commit fec4d7c2f1f741374b3a6bba16960ab232a8f3dd
Author: ProGamerGov <ProGamerGov@users.noreply.github.com>
Date:   Sun Jan 5 03:43:57 2025 -0700

    Viewcode: Fix issue with import paths that differ from the directory structure (#13195)
    
    Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

 AUTHORS.rst                                        |  2 +-
 CHANGES.rst                                        |  3 ++
 sphinx/ext/viewcode.py                             | 28 +++++++++++++++----
 tests/roots/test-ext-viewcode-find-package/conf.py | 24 ++++++++++++++++
 .../roots/test-ext-viewcode-find-package/index.rst | 10 +++++++
 .../main_package/__init__.py                       |  1 +
 .../main_package/subpackage/__init__.py            |  3 ++
 .../subpackage/_subpackage2/__init__.py            |  1 +
 .../subpackage/_subpackage2/submodule.py           | 32 ++++++++++++++++++++++
 tests/test_extensions/test_ext_viewcode.py         | 21 ++++++++++++++
 10 files changed, 119 insertions(+), 6 deletions(-)
 create mode 100644 tests/roots/test-ext-viewcode-find-package/conf.py
 create mode 100644 tests/roots/test-ext-viewcode-find-package/index.rst
 create mode 100644 tests/roots/test-ext-viewcode-find-package/main_package/__init__.py
 create mode 100644 tests/roots/test-ext-viewcode-find-package/main_package/subpackage/__init__.py
 create mode 100644 tests/roots/test-ext-viewcode-find-package/main_package/subpackage/_subpackage2/__init__.py
 create mode 100644 tests/roots/test-ext-viewcode-find-package/main_package/subpackage/_subpackage2/submodule.py
bisect run success

[adam-a-a]

@mrmundt mentions that sphinx toolbox may have a problem that was exposed by sphinx 8.2.0, rather than the bug being directly from sphinx 8.2.0.