MAINT: update build and CI for Sphinx 7 (#65)

* maint: update build and CI

* maint: revert version to current

* maint: more CI fixes,pre-commit

* maint: fix quoting

* maint: update pytest

* maint: fix spec

* maint: fix CI arg

* wip: improving deprecations

* maint: add type hints

* fix: patch regression

* maint: run pre-commit

* fix: copy doctree node to avoid mutation

* test: drop original_uri, translation_progress

* test: fix tests

* test: fix Sphinx 7 incompat

* maint: run pre-commit

.github/workflows/ci.yml

@@ -12,22 +12,22 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v1
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9
-      - uses: pre-commit/action@v2.0.0
+          python-version: "3.11"
+      - uses: pre-commit/action@v3.0.1
 
   tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.8, 3.9]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -36,14 +36,14 @@ jobs:
           pip install -e.[testing]
       - name: Run pytest
         run: |
-          pytest --duration=10 --cov=sphinx_exercise --cov-report=xml --cov-report=term-missing
+          pytest --durations=10 --cov=sphinx_exercise --cov-report=xml --cov-report=term-missing
       - name: Create cov
         run: coverage xml
       - name: Upload to Codecov
-        if: matrix.python-version == 3.8
-        uses: codecov/codecov-action@v1
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
         with:
-          name: sphinx-exercise-pytest-py3.8
+          name: sphinx-exercise-pytest-py3.11
           flags: pytests
           file: ./coverage.xml
           fail_ci_if_error: true
@@ -52,11 +52,11 @@ jobs:
     name: Documentation build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v1
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.11"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -74,15 +74,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v2
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v1
+        uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.11"
       - name: Build package
         run: |
-          pip install wheel
-          python setup.py bdist_wheel sdist
+          pip install wheel build
+          python -m build
       - name: Publish
         uses: pypa/[email protected]
         with:

.gitignore

@@ -13,3 +13,4 @@ dist/
 coverage.*
 coverage.xml
 .tox/
+.venv

.pre-commit-config.yaml

@@ -22,12 +22,9 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
-  - repo: https://github.com/PyCQA/flake8
-    rev: 5.0.4
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.4
     hooks:
-    - id: flake8
-
-  - repo: https://github.com/psf/black
-    rev: 22.8.0
-    hooks:
-      - id: black
+    - id: ruff
+      args: ["--fix", "--show-fixes"]
+    - id: ruff-format

pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinx-exercise"
+dynamic = ["version"]
+description = "A Sphinx extension for producing exercises and solutions."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+    { name = "QuantEcon", email = "[email protected]" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Plugins",
+    "Environment :: Web Environment",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Topic :: Documentation",
+    "Topic :: Documentation :: Sphinx",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Text Processing",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "sphinx-book-theme",
+    "sphinx>=5",
+]
+
+[project.optional-dependencies]
+all = [
+    "sphinx-exercise[code_style]",
+    "sphinx-exercise[rtd]",
+    "sphinx-exercise[testing]"
+]
+code_style = [
+    "black",
+    "flake8<3.8.0,>=3.7.0",
+    "pre-commit",
+]
+rtd = [
+    "myst-nb~=1.0.0",
+    "sphinx-book-theme",
+    "sphinx>=5,<8",
+]
+testing = [
+    "beautifulsoup4",
+    "coverage",
+    "matplotlib",
+    "myst-nb~=1.0.0",
+    "pytest-cov",
+    "pytest-regressions",
+    "pytest~=8.0.0",
+    "sphinx>=5,<8",
+    "texsoup",
+]
+
+[project.urls]
+Homepage = "https://github.com/executablebooks/sphinx-exercise"
+Source = "https://github.com/executablebooks/sphinx-exercise"
+Tracker = "https://github.com/executablebooks/sphinx-exercise/issues"
+
+[tool.hatch.version]
+path = "sphinx_exercise/__init__.py"

sphinx_exercise/__init__.py

@@ -7,6 +7,9 @@
 :license: MIT, see LICENSE for details.
 """
 
+__version__ = "0.4.1"
+
+
 from pathlib import Path
 from typing import Any, Dict, Set, Union, cast
 from sphinx.config import Config
@@ -17,6 +20,7 @@
 from sphinx.util import logging
 from sphinx.util.fileutil import copy_asset
 
+from ._compat import findall
 from .directive import (
     ExerciseDirective,
     ExerciseStartDirective,
@@ -129,7 +133,7 @@ def doctree_read(app: Sphinx, document: Node) -> None:
     domain = cast(StandardDomain, app.env.get_domain("std"))
 
     # Traverse sphinx-exercise nodes
-    for node in document.traverse():
+    for node in findall(document):
         if is_extension_node(node):
             name = node.get("names", [])[0]
             label = document.nameids[name]
@@ -140,7 +144,6 @@ def doctree_read(app: Sphinx, document: Node) -> None:
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
-
     app.add_config_value("hide_solutions", False, "env")
 
     app.connect("config-inited", init_numfig)  # event order - 1

sphinx_exercise/_compat.py

@@ -0,0 +1,9 @@
+from docutils.nodes import Element
+from typing import Iterator
+
+
+def findall(node: Element, *args, **kwargs) -> Iterator[Element]:
+    # findall replaces traverse in docutils v0.18
+    # note a difference is that findall is an iterator
+    impl = getattr(node, "findall", node.traverse)
+    return iter(impl(*args, **kwargs))

sphinx_exercise/directive.py

@@ -88,7 +88,6 @@ class : str,
     }
 
     def run(self) -> List[Node]:
-
         self.defaults = {"title_text": "Exercise"}
         self.serial_number = self.env.new_serialno()
 
@@ -160,7 +159,10 @@ def run(self) -> List[Node]:
         self.env.sphinx_exercise_registry[label] = {
             "type": self.name,
             "docname": self.env.docname,
-            "node": node,
+            # Copy the node so that the post transforms do not modify this original state
+            # Prior to Sphinx 6.1.0, the doctree was not cached, and Sphinx loaded a new copy
+            # c.f. https://github.com/sphinx-doc/sphinx/commit/463a69664c2b7f51562eb9d15597987e6e6784cd
+            "node": node.deepcopy(),
         }
 
         # TODO: Could tag this as Hidden to prevent the cell showing
@@ -214,7 +216,6 @@ class : str,
     solution_node = solution_node
 
     def run(self) -> List[Node]:
-
         self.defaults = {"title_text": "Solution to"}
         target_label = self.arguments[0]
         self.serial_number = self.env.new_serialno()

sphinx_exercise/latex.py

@@ -2,7 +2,6 @@
 
 
 class LaTeXMarkup(object):
-
     CR = "\n"
 
     def visit_admonition(self):