executablebooks · mmcky · Oct 21, 2025 · Oct 21, 2025 · Oct 21, 2025 · Oct 21, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,38 @@
 # Changelog
 
+## [v1.1.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.1.0) (2025-10-21)
+
+### Improved 👌
+
+- Modernized Python support: Now requires Python 3.11+ (dropped 3.9, 3.10)
+- Modernized Sphinx support: Now requires Sphinx 6+ (dropped Sphinx 4, 5)
+- Updated test suite with version-specific fixtures for Sphinx 7 and 8
+- Fixed Sphinx 9 deprecation warnings for better forward compatibility
+
+### Breaking Changes ⚠️
+
+- **Dropped Python 3.9 and 3.10 support** - Minimum Python version is now 3.11
+- **Dropped Sphinx <6 support** - Minimum Sphinx version is now 6.0
+
+## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-11-19)
+
+### Fixed 🐛
+
+- Fixed JupyterBuilder handling issue
+- Updated testing infrastructure and software versions
+
+## [v1.0.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.0) (2024-05-03)
+
+### Improved 👌
+
+- Updated build and CI for Sphinx 7 support
+- Pinned matplotlib to 3.7.* for testing
+- Updated to codecov 3
+- Modernized CI infrastructure
+
+### Breaking Changes ⚠️
+
+- **Updated minimum Sphinx version to 5.0** - Dropped support for Sphinx 4
 
 ## [v0.4.1](https://github.com/executablebooks/sphinx-exercise/tree/v0.4.1) (2023-1-23)
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "A Sphinx extension for producing exercises and solutions."
 readme = "README.md"
 license = { file = "LICENSE" }
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 authors = [
     { name = "QuantEcon", email = "admin@quantecon.org" },
 ]
@@ -22,10 +22,9 @@ classifiers = [
     "Natural Language :: English",
     "Operating System :: OS Independent",
     "Programming Language :: Python",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Documentation",
     "Topic :: Documentation :: Sphinx",
     "Topic :: Software Development :: Documentation",
@@ -34,7 +33,7 @@ classifiers = [
 ]
 dependencies = [
     "sphinx-book-theme",
-    "sphinx>=5",
+    "sphinx>=6",
 ]
 
 [project.optional-dependencies]
@@ -52,7 +51,7 @@ rtd = [
     "myst-nb~=1.0.0",
     "sphinx-book-theme",
     "sphinx_togglebutton",
-    "sphinx>=5,<8",
+    "sphinx>=6,<9",
 ]
 testing = [
     "beautifulsoup4",
@@ -62,7 +61,6 @@ testing = [
     "pytest-cov",
     "pytest-regressions",
     "pytest~=8.0.0",
-    "sphinx>=5,<8",
     "texsoup",
     "defusedxml", # Required by sphinx-testing
 ]

diff --git a/sphinx_exercise/directive.py b/sphinx_exercise/directive.py
@@ -9,9 +9,11 @@
 """
 
 from typing import List
+from pathlib import Path
 from docutils.nodes import Node
 
 from sphinx.util.docutils import SphinxDirective
+from sphinx.locale import get_translation
 from docutils.parsers.rst import directives
 from .nodes import (
     exercise_node,
@@ -29,7 +31,6 @@
 
 logger = logging.getLogger(__name__)
 
-from sphinx.locale import get_translation
 MESSAGE_CATALOG_NAME = "exercise"
 translate = get_translation(MESSAGE_CATALOG_NAME)
 
@@ -39,8 +40,8 @@ def duplicate_labels(self, label):
         """Check for duplicate labels"""
 
         if not label == "" and label in self.env.sphinx_exercise_registry.keys():
-            docpath = self.env.doc2path(self.env.docname)
-            path = docpath[: docpath.rfind(".")]
+            docpath = Path(self.env.doc2path(self.env.docname))
+            path = str(docpath.with_suffix(""))
             other_path = self.env.doc2path(
                 self.env.sphinx_exercise_registry[label]["docname"]
             )

diff --git a/sphinx_exercise/post_transforms.py b/sphinx_exercise/post_transforms.py
@@ -1,4 +1,5 @@
 import sphinx.addnodes as sphinx_nodes
+from pathlib import Path
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging
 from sphinx.builders.latex import LaTeXBuilder
@@ -194,8 +195,8 @@ def run(self):
                         docname = self.app.builder.current_docname
                     except AttributeError:
                         docname = self.env.docname  # for builder such as JupyterBuilder that don't support current_docname
-                docpath = self.env.doc2path(docname)
-                path = docpath[: docpath.rfind(".")]
+                docpath = Path(self.env.doc2path(docname))
+                path = str(docpath.with_suffix(""))
                 msg = f"undefined label: {target_label}"
                 logger.warning(msg, location=path, color="red")
                 return

diff --git a/tests/test_exercise_references.py b/tests/test_exercise_references.py
@@ -1,5 +1,8 @@
 from bs4 import BeautifulSoup
 import pytest
+import sphinx
+
+SPHINX_VERSION = f".sphinx{sphinx.version_info[0]}"
 
 
 @pytest.mark.sphinx("html", testroot="mybook")
@@ -35,7 +38,7 @@ def test_reference(app, idir, file_regression):
         excs += f"{ref}\n"
 
     file_regression.check(
-        str(excs[:-1]), basename=idir.split(".")[0], extension=".html"
+        str(excs[:-1]), basename=idir.split(".")[0], extension=f"{SPHINX_VERSION}.html"
     )
 
 
@@ -67,4 +70,5 @@ def test_exercise_doctree(app, docname, file_regression, get_sphinx_app_doctree)
         resolve=False,
         regress=True,
         flatten_outdir=True,  # noqa: E501 flatten files "solution/<file> -> <file>.xml" for convenience
+        sphinx_version=SPHINX_VERSION,
     )
diff --git a/...se_references/_enum_numref_mathtitle.html → ...ences/_enum_numref_mathtitle.sphinx7.html b/...se_references/_enum_numref_mathtitle.html → ...ences/_enum_numref_mathtitle.sphinx7.html
diff --git a/tests/test_exercise_references/_enum_numref_mathtitle.sphinx7.xml b/tests/test_exercise_references/_enum_numref_mathtitle.sphinx7.xml
@@ -0,0 +1,28 @@
+<document source="_enum_numref_mathtitle.rst">
+    <section ids="enum-numref-mathtitle" names="_enum_numref_mathtitle">
+        <title>
+            _enum_numref_mathtitle
+        <paragraph>
+            This is a reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="False" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    test-exc-label-math
+            .
+        <paragraph>
+            This is a second reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text %s
+            .
+        <paragraph>
+            This is a third reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {number}
+            .
+        <paragraph>
+            This is a fourth reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {name}
+            .
diff --git a/tests/test_exercise_references/_enum_numref_mathtitle.sphinx8.html b/tests/test_exercise_references/_enum_numref_mathtitle.sphinx8.html
@@ -0,0 +1,6 @@
+<p>This is a reference <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">Exercise 1</span></a>.</p>
+<p>This is a second reference <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some text 1</span></a>.</p>
+<p>This is a third reference <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some text 1</span></a>.</p>
+<p>This is a fourth reference <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some text Exercise</span></a>.</p>
+<p class="topless"><a href="_enum_numref_title.html" title="previous chapter">_enum_numref_title</a></p>
+<p class="topless"><a href="_unenum_mathtitle_label.html" title="next chapter">_unenum_mathtitle_label</a></p>
diff --git a/tests/test_exercise_references/_enum_numref_mathtitle.sphinx8.xml b/tests/test_exercise_references/_enum_numref_mathtitle.sphinx8.xml
@@ -0,0 +1,28 @@
+<document source="_enum_numref_mathtitle.rst">
+    <section ids="enum-numref-mathtitle" names="_enum_numref_mathtitle">
+        <title>
+            _enum_numref_mathtitle
+        <paragraph>
+            This is a reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="False" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    test-exc-label-math
+            .
+        <paragraph>
+            This is a second reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text %s
+            .
+        <paragraph>
+            This is a third reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {number}
+            .
+        <paragraph>
+            This is a fourth reference 
+            <pending_xref refdoc="exercise/_enum_numref_mathtitle" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {name}
+            .
diff --git a/...cise_references/_enum_numref_notitle.html → ...erences/_enum_numref_notitle.sphinx7.html b/...cise_references/_enum_numref_notitle.html → ...erences/_enum_numref_notitle.sphinx7.html
diff --git a/tests/test_exercise_references/_enum_numref_notitle.sphinx7.xml b/tests/test_exercise_references/_enum_numref_notitle.sphinx7.xml
@@ -0,0 +1,28 @@
+<document source="_enum_numref_notitle.rst">
+    <section ids="enum-numref-notitle" names="_enum_numref_notitle">
+        <title>
+            _enum_numref_notitle
+        <paragraph>
+            This is a reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="False" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    text-exc-notitle
+            .
+        <paragraph>
+            This is a second reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text %s
+            .
+        <paragraph>
+            This is a third reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {number}
+            .
+        <paragraph>
+            This is a fourth reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {name}
+            .
diff --git a/tests/test_exercise_references/_enum_numref_notitle.sphinx8.html b/tests/test_exercise_references/_enum_numref_notitle.sphinx8.html
@@ -0,0 +1,6 @@
+<p>This is a reference <a class="reference internal" href="_enum_notitle_label.html#text-exc-notitle"><span class="std std-numref">Exercise 2</span></a>.</p>
+<p>This is a second reference <a class="reference internal" href="_enum_notitle_label.html#text-exc-notitle"><span class="std std-numref">some text 2</span></a>.</p>
+<p>This is a third reference <a class="reference internal" href="_enum_notitle_label.html#text-exc-notitle"><span class="std std-numref">some text 2</span></a>.</p>
+<p>This is a fourth reference <a class="reference internal" href="_enum_notitle_label.html#text-exc-notitle"><span class="std std-numref">some text Exercise</span></a>.</p>
+<p class="topless"><a href="_enum_ref_mathtitle.html" title="previous chapter">_enum_ref_mathtitle</a></p>
+<p class="topless"><a href="_enum_numref_title.html" title="next chapter">_enum_numref_title</a></p>
diff --git a/tests/test_exercise_references/_enum_numref_notitle.sphinx8.xml b/tests/test_exercise_references/_enum_numref_notitle.sphinx8.xml
@@ -0,0 +1,28 @@
+<document source="_enum_numref_notitle.rst">
+    <section ids="enum-numref-notitle" names="_enum_numref_notitle">
+        <title>
+            _enum_numref_notitle
+        <paragraph>
+            This is a reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="False" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    text-exc-notitle
+            .
+        <paragraph>
+            This is a second reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text %s
+            .
+        <paragraph>
+            This is a third reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {number}
+            .
+        <paragraph>
+            This is a fourth reference 
+            <pending_xref refdoc="exercise/_enum_numref_notitle" refdomain="std" refexplicit="True" reftarget="text-exc-notitle" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some text {name}
+            .
diff --git a/...references/_enum_numref_placeholders.html → ...es/_enum_numref_placeholders.sphinx7.html b/...references/_enum_numref_placeholders.html → ...es/_enum_numref_placeholders.sphinx7.html
diff --git a/tests/test_exercise_references/_enum_numref_placeholders.sphinx7.xml b/tests/test_exercise_references/_enum_numref_placeholders.sphinx7.xml
@@ -0,0 +1,64 @@
+<document source="_enum_numref_placeholders.rst">
+    <section ids="enum-numref-placeholders" names="_enum_numref_placeholders">
+        <title>
+            _enum_numref_placeholders
+        <paragraph>
+            This reference does not include math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {number} text %s test {name}
+            .
+        <paragraph>
+            This reference does not include math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {number} text %s test
+            .
+        <paragraph>
+            This reference does not include math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {name} text %s test
+            .
+        <paragraph>
+            This reference does not include math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {name} text {number} test
+            .
+        <paragraph>
+            This reference does not include math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some %s text test
+            .
+        <paragraph>
+            This reference includes math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {number} text %s test {name}
+            .
+        <paragraph>
+            This reference includes math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {number} text %s test
+            .
+        <paragraph>
+            This reference includes math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {name} text %s test
+            .
+        <paragraph>
+            This reference includes math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some {name} text {number} test
+            .
+        <paragraph>
+            This reference includes math 
+            <pending_xref refdoc="exercise/_enum_numref_placeholders" refdomain="std" refexplicit="True" reftarget="test-exc-label-math" reftype="numref" refwarn="True">
+                <literal classes="xref std std-numref">
+                    some %s text test
+            .
diff --git a/tests/test_exercise_references/_enum_numref_placeholders.sphinx8.html b/tests/test_exercise_references/_enum_numref_placeholders.sphinx8.html
@@ -0,0 +1,12 @@
+<p>This reference does not include math <a class="reference internal" href="_enum_title_class_label.html#test-exc-label"><span class="std std-numref">some 3 text %s test Exercise</span></a>.</p>
+<p>This reference does not include math <a class="reference internal" href="_enum_title_class_label.html#test-exc-label"><span class="std std-numref">some 3 text %s test</span></a>.</p>
+<p>This reference does not include math <a class="reference internal" href="_enum_title_class_label.html#test-exc-label"><span class="std std-numref">some Exercise text %s test</span></a>.</p>
+<p>This reference does not include math <a class="reference internal" href="_enum_title_class_label.html#test-exc-label"><span class="std std-numref">some Exercise text 3 test</span></a>.</p>
+<p>This reference does not include math <a class="reference internal" href="_enum_title_class_label.html#test-exc-label"><span class="std std-numref">some 3 text test</span></a>.</p>
+<p>This reference includes math <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some 1 text %s test Exercise</span></a>.</p>
+<p>This reference includes math <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some 1 text %s test</span></a>.</p>
+<p>This reference includes math <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some Exercise text %s test</span></a>.</p>
+<p>This reference includes math <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some Exercise text 1 test</span></a>.</p>
+<p>This reference includes math <a class="reference internal" href="_enum_mathtitle_label.html#test-exc-label-math"><span class="std std-numref">some 1 text test</span></a>.</p>
+<p class="topless"><a href="_unenum_numref_mathtitle.html" title="previous chapter">_unenum_numref_mathtitle</a></p>
+<p class="topless"><a href="_enum_duplicate_label.html" title="next chapter">_enum_duplicate_label</a></p>