🔧 test fixes for sphinx 7.4 (#945)

Author: chrisjsewell

.github/workflows/test-formats.yml

@@ -54,23 +54,23 @@ jobs:
     - name: Build docs
       run: |
         sphinx-build -nW --keep-going -b ${{ matrix.format }} docs/ docs/_build/${{ matrix.format }}
-
-    - name: Make PDF
-      uses: xu-cheng/latex-action@v2
-      with:
-        working_directory: docs/_build/latex
-        root_file: "mystparser.tex"
-        # https://github.com/marketplace/actions/github-action-for-latex#it-fails-due-to-xindy-cannot-be-found
-        pre_compile: |
-          ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/xindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/xindy
-          ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/texindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/texindy
-          wget https://sourceforge.net/projects/xindy/files/xindy-source-components/2.4/xindy-kernel-3.0.tar.gz
-          tar xf xindy-kernel-3.0.tar.gz
-          cd xindy-kernel-3.0/src
-          apk add make
-          apk add clisp --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community
-          make
-          cp -f xindy.mem /opt/texlive/texdir/bin/x86_64-linuxmusl/
-          cd ../../
-      env:
-        XINDYOPTS: -L english -C utf8  -M sphinx.xdy
+    # TODO https://github.com/sphinx-doc/sphinx/issues/12594
+    # - name: Make PDF
+    #   uses: xu-cheng/latex-action@v2
+    #   with:
+    #     working_directory: docs/_build/latex
+    #     root_file: "mystparser.tex"
+    #     # https://github.com/marketplace/actions/github-action-for-latex#it-fails-due-to-xindy-cannot-be-found
+    #     pre_compile: |
+    #       ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/xindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/xindy
+    #       ln -sf /opt/texlive/texdir/texmf-dist/scripts/xindy/texindy.pl /opt/texlive/texdir/bin/x86_64-linuxmusl/texindy
+    #       wget https://sourceforge.net/projects/xindy/files/xindy-source-components/2.4/xindy-kernel-3.0.tar.gz
+    #       tar xf xindy-kernel-3.0.tar.gz
+    #       cd xindy-kernel-3.0/src
+    #       apk add make
+    #       apk add clisp --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community
+    #       make
+    #       cp -f xindy.mem /opt/texlive/texdir/bin/x86_64-linuxmusl/
+    #       cd ../../
+    #   env:
+    #     XINDYOPTS: -L english -C utf8  -M sphinx.xdy

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
       args: [--config-file=pyproject.toml]
       additional_dependencies:
       - types-urllib3
-      - sphinx~=7.3
+      - sphinx~=7.4
       - markdown-it-py~=3.0
       - mdit-py-plugins~=0.4.0
       files: >

CHANGELOG.md

@@ -135,7 +135,7 @@ Full Changelog: [v0.18.1...v0.19.0](https://github.com/executablebooks/MyST-Pars
 ### 📚 Rewritten documentation
 
 The documentation has been almost completely rewritten,
-with a clearer structure, many more examples, rich hover tips, and a new live preview page ⚡️ (powered by [pyscript](https://pyscript.readthedocs.io/), <gh-pr:717>).
+with a clearer structure, many more examples, rich hover tips, and a new live preview page (powered by [pyscript](https://pyscript.readthedocs.io/), <gh-pr:717>).
 
 The code base API is also now fully documented by [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io/), which even allows for MyST docstrings! (<gh-pr:704>).
 

docs/develop/background.md

@@ -11,7 +11,7 @@ but there is no community standard around various syntactic choices for these fe
 Sphinx is a documentation generation framework written in Python. It heavily-utilizes
 reStructuredText syntax, which is another markup language for writing documents. In
 particular, Sphinx defines two extension points that are extremely useful:
-**{ref}`in-line roles<sphinx:rst-roles-alt>`** and **{ref}`block-level directives <sphinx:rst-directives>`**.
+**{ref}`in-line roles<sphinx:rst-roles>`** and **{ref}`block-level directives <sphinx:rst-directives>`**.
 
 **This project is an attempt at combining the simplicity and readability of Markdown
 with the power and flexibility of reStructuredText and the Sphinx platform.** It

docs/live-preview.md

@@ -8,7 +8,7 @@ py-config:
     - pygments
 ---
 
-# ⚡️ Live Preview
+# ⚡ Live Preview
 
 This is a live preview of the MyST Markdown [docutils renderer](docutils.md).
 You can edit the text/configuration below and see the live output.

myst_parser/mdit_to_docutils/base.py

@@ -1596,7 +1596,7 @@ def render_dl(self, token: SyntaxTreeNode) -> None:
                             term = make_glossary_term(
                                 self.sphinx_env,  # type: ignore[arg-type]
                                 term.children,
-                                None,  # type: ignore[arg-type]
+                                None,
                                 term.source,
                                 term.line,
                                 node_id=None,

myst_parser/sphinx_ext/main.py

@@ -2,6 +2,7 @@
 
 from typing import Any
 
+import sphinx
 from docutils import nodes
 from sphinx.application import Sphinx
 
@@ -42,9 +43,11 @@ def setup_sphinx(app: Sphinx, load_parser: bool = False) -> None:
 
     # override only the html writer visit methods for rubric, to use the "level" attribute
     # this allows for nested headers to be correctly rendered
-    app.add_node(
-        nodes.rubric, override=True, html=(visit_rubric_html, depart_rubric_html)
-    )
+    if sphinx.version_info < (7, 4):
+        # This is now added in sphinx: https://github.com/sphinx-doc/sphinx/pull/12506
+        app.add_node(
+            nodes.rubric, override=True, html=(visit_rubric_html, depart_rubric_html)
+        )
     # override only the html writer visit methods for container,
     # to remove the "container" class for divs
     # this avoids CSS clashes with the bootstrap theme

myst_parser/sphinx_ext/mathjax.py

@@ -61,7 +61,7 @@ def override_mathjax(app: Sphinx):
 
     if "mathjax3_config" in app.config:
         # sphinx 4 + mathjax 3
-        app.config.mathjax3_config = app.config.mathjax3_config or {}  # type: ignore[attr-defined]
+        app.config.mathjax3_config = app.config.mathjax3_config or {}
         app.config.mathjax3_config.setdefault("options", {})
         if (
             "processHtmlClass" in app.config.mathjax3_config["options"]
@@ -77,7 +77,7 @@ def override_mathjax(app: Sphinx):
         app.config.mathjax3_config["options"]["processHtmlClass"] = mjax_classes
     elif "mathjax_config" in app.config:
         # sphinx 3 + mathjax 2
-        app.config.mathjax_config = app.config.mathjax_config or {}  # type: ignore[attr-defined]
+        app.config.mathjax_config = app.config.mathjax_config or {}
         app.config.mathjax_config.setdefault("tex2jax", {})
         if (
             "processClass" in app.config.mathjax_config["tex2jax"]

tests/test_sphinx/test_sphinx_builds.py

@@ -432,6 +432,8 @@ def test_gettext(
     output = re.sub(r"POT-Creation-Date: [0-9: +-]+", "POT-Creation-Date: ", output)
     output = re.sub(r"Copyright \(C\) [0-9]{4}", "Copyright (C) XXXX", output)
 
+    if sphinx.version_info < (7, 4):
+        output = output.replace("Python ", "Project name not set ")
     file_regression.check(output, extension=".pot")
 
 
@@ -512,6 +514,8 @@ def test_gettext_additional_targets(
     output = re.sub(r"POT-Creation-Date: [0-9: +-]+", "POT-Creation-Date: ", output)
     output = re.sub(r"Copyright \(C\) [0-9]{4}", "Copyright (C) XXXX", output)
 
+    if sphinx.version_info < (7, 4):
+        output = output.replace("Python ", "Project name not set ")
     file_regression.check(output, extension=".pot")
 
 

tests/test_sphinx/test_sphinx_builds/test_gettext.pot

@@ -1,12 +1,12 @@
 # SOME DESCRIPTIVE TITLE.
 # Copyright (C) XXXX, Executable Book Project
-# This file is distributed under the same license as the Python package.
+# This file is distributed under the same license as the Project name not set package.
 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
 #
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: Python \n"
+"Project-Id-Version: Project name not set \n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: \n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"