Merge main into update-languages

Resolved merge conflicts in:
- sphinx_exercise/directive.py: Accepted alphabetically sorted imports from main
- sphinx_exercise/nodes.py: Removed extra blank line

This merge brings in all the test suite modernization from main including:
- Python 3.11-3.13 and Sphinx 6-8 compatibility
- Complete pathlib migration (os.path -> pathlib.Path)
- Image hash normalization for cross-platform tests
- All test fixtures for Sphinx 6, 7, and 8

Author: mmcky

.github/workflows/ci.yml

@@ -23,7 +23,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
+        sphinx-version: ["6", "7", "8"]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
@@ -34,16 +35,17 @@ jobs:
         run : |
           python -m pip install --upgrade pip
           pip install -e.[testing]
+          pip install "sphinx>=${{ matrix.sphinx-version }},<${{ matrix.sphinx-version == '6' && '7' || matrix.sphinx-version == '7' && '8' || '9' }}"
       - name: Run pytest
         run: |
           pytest --durations=10 --cov=sphinx_exercise --cov-report=xml --cov-report=term-missing
       - name: Create cov
         run: coverage xml
       - name: Upload to Codecov
-        if: false && (matrix.python-version == '3.11')
+        if: false && (matrix.python-version == '3.11' && matrix.sphinx-version == '8')
         uses: codecov/codecov-action@v4
         with:
-          name: sphinx-exercise-pytest-py3.11
+          name: sphinx-exercise-pytest-py3.11-sphinx8
           token: "${{ secrets.CODECOV_TOKEN }}"
           flags: pytests
           file: ./coverage.xml

CHANGELOG.md

@@ -27,6 +27,25 @@
 
 _No changelog available for this version._
 
+## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-07-01)
+
+### Improved 👌
+
+- Updates to testing infrastructure and minor bug fixes
+- Fixed JupyterBuilder handling in test suite
+
+## [v1.0.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.0) (2024-01-15)
+
+### Improved 👌
+
+- Added support for Sphinx 7
+- Updated build and CI infrastructure
+- Fixed deprecation warnings for Sphinx 7 compatibility
+- Improved type hints throughout codebase
+- Fixed doctree node mutation issues by copying nodes
+- Updated codecov to version 3
+- Pinned matplotlib to 3.7.* for testing stability
+
 ## [v0.4.1](https://github.com/executablebooks/sphinx-exercise/tree/v0.4.1) (2023-1-23)
 
 ### Improved 👌

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 = "[email protected]" },
 ]
@@ -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.1",
 ]
 
 [project.optional-dependencies]
@@ -49,20 +48,20 @@ code_style = [
     "pre-commit",
 ]
 rtd = [
-    "myst-nb~=1.0.0",
+    "myst-nb>=1.1.0",
     "sphinx-book-theme",
     "sphinx_togglebutton",
-    "sphinx>=5,<8",
+    "sphinx>=6.1,<9",
 ]
 testing = [
     "beautifulsoup4",
     "coverage",
-    "matplotlib==3.8.*",
-    "myst-nb~=1.0.0",
+    "matplotlib>=3.8",
+    "myst-nb>=1.1.0",
     "pytest-cov",
     "pytest-regressions",
-    "pytest~=8.0.0",
-    "sphinx>=5,<8",
+    "pytest>=8.0",
+    "sphinx>=6.1,<9",
     "texsoup",
     "defusedxml", # Required by sphinx-testing
 ]

sphinx_exercise/__init__.py

@@ -9,7 +9,6 @@
 
 __version__ = "1.0.1"
 
-import os
 from pathlib import Path
 from typing import Any, Dict, Set, Union, cast
 from sphinx.config import Config
@@ -215,9 +214,9 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_css_file("exercise.css")
 
     # add translations
-    package_dir = os.path.abspath(os.path.dirname(__file__))
-    locale_dir = os.path.join(package_dir, "translations", "locales")
-    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+    package_dir = Path(__file__).parent.resolve()
+    locale_dir = package_dir / "translations" / "locales"
+    app.add_message_catalog(MESSAGE_CATALOG_NAME, str(locale_dir))
 
     return {
         "version": "builtin",

sphinx_exercise/directive.py

@@ -8,23 +8,25 @@
 :licences: see LICENSE for details
 """
 
+from pathlib import Path
 from typing import List
-from docutils.nodes import Node
+
 from docutils import nodes
+from docutils.nodes import Node
 from docutils.parsers.rst import directives
-from sphinx.util.docutils import SphinxDirective
-from sphinx.util import logging
 from sphinx.locale import get_translation
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
 
 from .nodes import (
-    exercise_node,
-    exercise_enumerable_node,
     exercise_end_node,
+    exercise_enumerable_node,
+    exercise_node,
+    exercise_subtitle,
+    exercise_title,
+    solution_end_node,
     solution_node,
     solution_start_node,
-    solution_end_node,
-    exercise_title,
-    exercise_subtitle,
     solution_title,
 )
 
@@ -40,7 +42,7 @@ def duplicate_labels(self, label):
 
         if not label == "" and label in self.env.sphinx_exercise_registry.keys():
             docpath = self.env.doc2path(self.env.docname)
-            path = docpath[: docpath.rfind(".")]
+            path = str(Path(docpath).with_suffix(""))
             other_path = self.env.doc2path(
                 self.env.sphinx_exercise_registry[label]["docname"]
             )

sphinx_exercise/post_transforms.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 import sphinx.addnodes as sphinx_nodes
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging
@@ -195,7 +197,7 @@ def run(self):
                     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(".")]
+                path = str(Path(docpath).with_suffix(""))
                 msg = f"undefined label: {target_label}"
                 logger.warning(msg, location=path, color="red")
                 return

sphinx_exercise/translations/_convert.py

@@ -1,5 +1,4 @@
 import json
-import os
 from pathlib import Path
 import subprocess
 
@@ -54,9 +53,9 @@ def convert_json(folder=None):
         subprocess.check_call(
             [
                 "msgfmt",
-                os.path.abspath(path),
+                str(path.resolve()),
                 "-o",
-                os.path.abspath(path.parent / f"{MESSAGE_CATALOG_NAME}.mo"),
+                str((path.parent / f"{MESSAGE_CATALOG_NAME}.mo").resolve()),
             ]
         )
 

tests/books/test-gateddirective/solution-exercise-gated.md

@@ -42,7 +42,7 @@ axs[0].set_xlabel('time')
 axs[0].set_ylabel('s1 and s2')
 axs[0].grid(True)
 
-cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt)
+cxy, f = axs[1].cohere(s1, s2, NFFT=256, Fs=1. / dt)
 axs[1].set_ylabel('coherence')
 
 fig.tight_layout()
@@ -87,7 +87,7 @@ axs[0].set_xlabel('time')
 axs[0].set_ylabel('s1 and s2')
 axs[0].grid(True)
 
-cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt)
+cxy, f = axs[1].cohere(s1, s2, NFFT=256, Fs=1. / dt)
 axs[1].set_ylabel('coherence')
 
 fig.tight_layout()

tests/books/test-gateddirective/solution-exercise.md

@@ -42,7 +42,7 @@ axs[0].set_xlabel('time')
 axs[0].set_ylabel('s1 and s2')
 axs[0].grid(True)
 
-cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt)
+cxy, f = axs[1].cohere(s1, s2, NFFT=256, Fs=1. / dt)
 axs[1].set_ylabel('coherence')
 
 fig.tight_layout()
@@ -85,7 +85,7 @@ axs[0].set_xlabel('time')
 axs[0].set_ylabel('s1 and s2')
 axs[0].grid(True)
 
-cxy, f = axs[1].cohere(s1, s2, 256, 1. / dt)
+cxy, f = axs[1].cohere(s1, s2, NFFT=256, Fs=1. / dt)
 axs[1].set_ylabel('coherence')
 
 fig.tight_layout()

tests/conftest.py

@@ -15,7 +15,8 @@
     def rootdir(tmpdir):
         from sphinx.testing.path import path
 
-        src = path(__file__).parent.absolute() / "books"
+        # In Sphinx 6, path objects don't have .absolute() method, but they are already absolute
+        src = path(__file__).parent / "books"
         dst = tmpdir.join("books")
         shutil.copytree(src, dst)
         yield path(dst)
@@ -94,6 +95,10 @@ class FileRegression:
         (r"original_uri=\"[^\"]*\"\s", ""),
         # TODO: Remove when support for Sphinx<7.2 is dropped
         ("Link to", "Permalink to"),
+        # Strip ipykernel process IDs (temporary directory paths)
+        (r"ipykernel_\d+", "ipykernel_XXXXX"),
+        # Normalize matplotlib image hashes (platform/version dependent)
+        (r"[a-f0-9]{64}\.png", "IMAGEHASH.png"),
     )
 
     def __init__(self, file_regression):