🔧 Modernize packaging, tooling and CI (#21)

All CI jobs were failing: Python 3.7-3.9 are no longer available on
ubuntu-latest runners, and the tests that did run failed against modern
Sphinx/docutils.

- Packaging: require Python >=3.11 and sphinx>=8,<10; update classifiers,
  project URLs (repo moved to sphinx-extensions2) and flit sdist excludes
- Drop the docutils<0.18 findall/traverse compatibility shim
- Lint: replace black/isort/flake8/pyupgrade with ruff-check + ruff-format
- CI: add a pre-commit job; test matrix of py3.11-3.14 x sphinx 8/9 (plus
  Windows); add a PyPI trusted-publishing job on version tags
- tox: py{311-314}-sphinx{8,9} and docs-{update,clean} environments
- Read the Docs: ubuntu-24.04/py3.12 and the now-required configuration key
- Tests: make the .tex output filename version-agnostic (Sphinx >=7.2
  renamed the default project); serialize the is_subfigure attribute as a
  string so doctree fixtures are stable across docutils 0.21/0.22

All 15 tests pass against both sphinx 8.2/docutils 0.21 and
sphinx 9.0/docutils 0.22, and the docs build warning-free on Sphinx 9.


Claude-Session: https://claude.ai/code/session_01CQYXtJrMEhZWpJVvBcx7ff

Co-authored-by: Claude <noreply@anthropic.com>

Author: chrisjsewell

.github/workflows/ci.yml

@@ -9,30 +9,73 @@ on:
 
 jobs:
 
+  pre-commit:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.11"
+    - uses: pre-commit/action@v3.0.1
+
   tests:
 
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        sphinx: [">=8,<9", ">=9,<10"]
         os: [ubuntu-latest]
         include:
         - os: windows-latest
-          python-version: "3.8"
+          python-version: "3.11"
+          sphinx: ">=8,<9"
+        - os: windows-latest
+          python-version: "3.14"
+          sphinx: ">=9,<10"
 
     runs-on: ${{ matrix.os }}
 
+    name: "pytest: py${{ matrix.python-version }}, sphinx${{ matrix.sphinx }}, on ${{ matrix.os }}"
+
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[testing]
+        pip install -e ".[testing]" "sphinx${{ matrix.sphinx }}"
     - name: Run pytest
-      run: pytest --cov=src --cov-report=xml --cov-report=term-missing
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      run: pytest --cov=sphinx_subfigure --cov-report=term-missing
+
+  publish:
+
+    name: Publish to PyPI
+    needs: [pre-commit, tests]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && github.repository == 'sphinx-extensions2/sphinx-subfigure'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sphinx-subfigure/
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v6
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+    - name: Build package
+      run: |
+        python -m pip install build
+        python -m build
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.pre-commit-config.yaml

@@ -2,32 +2,15 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
 
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
     hooks:
-    - id: pyupgrade
-      args: [--py37-plus]
-
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.13.2
-    hooks:
-    - id: isort
-
-  - repo: https://github.com/psf/black
-    rev: 23.12.1
-    hooks:
-      - id: black
-
-  - repo: https://github.com/PyCQA/flake8
-    rev: 7.0.0
-    hooks:
-    - id: flake8
-      additional_dependencies:
-        - flake8-comprehensions
-        - flake8-bugbear
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

.readthedocs.yml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.8"
+    python: "3.12"
 
 python:
   install:
@@ -14,6 +14,7 @@ python:
 
 sphinx:
   builder: html
+  configuration: docs/conf.py
   fail_on_warning: true
 
 # Also build PDF & ePub

AGENTS.md

@@ -27,8 +27,7 @@ src/sphinx_subfigure/
 ├── __init__.py             # __version__ and setup() re-export
 ├── main.py                 # SubfigureDirective: content parsing, layout generation + validation
 ├── tr_html.py              # HTML post-transform, grid/item nodes, responsive CSS injection
-├── tr_latex.py             # LaTeX post-transform, subfigure environment nodes
-└── _compat.py              # docutils <0.18 findall/traverse compatibility
+└── tr_latex.py             # LaTeX post-transform, subfigure environment nodes
 
 tests/
 ├── test_simple.py          # all tests (pytest-param-files + sphinx-pytest)
@@ -116,8 +115,11 @@ Tests can also be run via `tox` (e.g. `tox -e py311`).
 ### Documentation
 
 ```bash
-# Build docs (also: BUILDER=linkcheck tox -e docs)
-tox -e docs
+# Build docs from clean (also: BUILDER=linkcheck tox -e docs-clean)
+tox -e docs-clean
+
+# Incremental docs build
+tox -e docs-update
 
 # Or manually
 pip install -e ".[docs]"
@@ -165,8 +167,8 @@ pre-commit run --all-files
   annotation syntax (`list[str]`, `X | None`)
 - Complete type annotations on all function signatures
 - Sphinx-style docstrings; short module docstrings on every module
-- Style is enforced by pre-commit (see `.pre-commit-config.yaml`); run
-  `pre-commit run --all-files` before committing
+- Style is enforced by pre-commit (see `.pre-commit-config.yaml`), using `ruff-check`
+  (with `--fix`) and `ruff-format`; run `pre-commit run --all-files` before committing
 - User-facing directive errors should be raised via `self.error(...)` inside the
   directive, with messages prefixed to identify the failing option
   (e.g. `Invalid subfigure layout-sm (...)`)

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["flit_core >=3.2,<4"]
+requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
 
 [project]
@@ -12,31 +12,43 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Text Processing :: Markup",
     "Framework :: Sphinx :: Extension",
 ]
 keywords = ["sphinx", "subfigure"]
-requires-python = ">=3.7"
-dependencies = ["sphinx"]
+requires-python = ">=3.11"
+dependencies = ["sphinx>=8,<10"]
 
-[project."optional-dependencies"]
+[project.optional-dependencies]
 testing = [
+    "beautifulsoup4",
+    "defusedxml",
     "pytest",
     "pytest-cov",
-    "pytest-regressions",
-    "pytest-param-files",
-    "sphinx-pytest>=0.0.4",
-    "beautifulsoup4",
+    "pytest-param-files~=0.6.0",
+    "sphinx-pytest~=0.3.0",
 ]
 docs = [
     "myst-parser",
     "furo"
 ]
 
 [project.urls]
-Homepage = "https://github.com/chrisjsewell/sphinx-subfigure"
+Homepage = "https://github.com/sphinx-extensions2/sphinx-subfigure"
+Documentation = "https://sphinx-subfigure.readthedocs.io"
+
+[tool.flit.sdist]
+exclude = [
+    "docs/",
+    "tests/",
+]
 
-[tool.isort]
-profile = "black"
-force_sort_within_sections = true
+[tool.ruff.lint]
+extend-select = ["B", "C4", "FA", "FURB", "I", "ICN", "ISC", "N", "PERF", "PGH", "PIE", "RUF", "SIM", "UP"]
+extend-ignore = ["ISC001", "RUF005", "RUF012"]

src/sphinx_subfigure/_compat.py

@@ -44,8 +44,10 @@ class SubfigureDirective(SphinxDirective):
     def run(self) -> list[nodes.Element]:
         """Run the directive."""
         self.assert_has_content()
+        # note the attribute value is a string, not a bool,
+        # so that its doctree serialization is stable across docutils versions
         figure_node = nodes.figure(
-            is_subfigure=True,
+            is_subfigure="true",
             classes=["sphinx-subfigure"] + self.options.get("class", []),
             grid_classes=self.options.get("class-grid", []),
             area_classes=self.options.get("class-area", []),
@@ -126,7 +128,7 @@ def _validate_layout(
 
         prefix = f"Invalid subfigure {ltype}"
 
-        area_indices: dict[str, list[tuple[int, int]]] = {}
+        area_indices: dict[str, set[tuple[int, int]]] = {}
 
         # check all rows have the same number of columns, and retrieve indices of each area
         if not layout:

src/sphinx_subfigure/main.py

@@ -8,8 +8,6 @@
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.writers.html import HTMLTranslator
 
-from ._compat import findall
-
 
 def setup_html(app: Sphinx):
     """Setup the extension for HTML building."""
@@ -112,9 +110,8 @@ class SubfigureHtmlTransform(SphinxPostTransform):
     def run(self) -> None:
         """Run the transform."""
 
-        # docutils <0.18 (traverse) >=0.18 (findall) compatibility
-        for fig_node in findall(
-            self.document, lambda n: "is_subfigure" in getattr(n, "attributes", {})
+        for fig_node in self.document.findall(
+            lambda n: "is_subfigure" in getattr(n, "attributes", {})
         ):
             # initiate figure children
             children = []
@@ -127,9 +124,9 @@ def run(self) -> None:
                 layout_class = f"ss-layout-{size}-" + "_".join(
                     ["".join(a.replace(".", "d") for a in row) for row in layout]
                 )
-                self.document["subfig_layouts"].setdefault(size, {})[
-                    layout_class
-                ] = layout
+                self.document["subfig_layouts"].setdefault(size, {})[layout_class] = (
+                    layout
+                )
                 classes.append(layout_class)
 
             # add grid

src/sphinx_subfigure/tr_html.py

@@ -7,8 +7,6 @@
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.writers.latex import LaTeXTranslator
 
-from ._compat import findall
-
 
 def setup_latex(app: Sphinx):
     """Setup the extension for LaTeX building."""
@@ -50,9 +48,8 @@ class SubfigureLaTexTransform(SphinxPostTransform):
     def run(self) -> None:
         """Run the transform."""
 
-        # docutils <0.18 (traverse) >=0.18 (findall) compatibility
-        for fig_node in findall(
-            self.document, lambda n: "is_subfigure" in getattr(n, "attributes", {})
+        for fig_node in self.document.findall(
+            lambda n: "is_subfigure" in getattr(n, "attributes", {})
         ):
             layout = fig_node["layout"]["default"]
             if not layout:

src/sphinx_subfigure/tr_latex.py

@@ -9,7 +9,7 @@ simple
       :alt: hallo
 .
 <document source="<src>/index.rst" subfig_layouts="{'default': {'ss-layout-default-AB': [['A', 'B']]}}">
-    <figure area_classes="" classes="sphinx-subfigure" grid_classes="" is_subfigure="True" layout="{'default': [['A', 'B']]}">
+    <figure area_classes="" classes="sphinx-subfigure" grid_classes="" is_subfigure="true" layout="{'default': [['A', 'B']]}">
         <SubfigureGridHtml classes="sphinx-subfigure-grid ss-layout-default-AB">
             <SubfigureGridItemHtml area="A" classes="sphinx-subfigure-area">
                 <image alt="hallo" candidates="{'*': 'image.png'}" subfigure_area="A" uri="image.png">