🔧 Replace rye with tox and add sphinx-needs version matrix (#65)

Rye was only used for script shortcuts and dev dependency management,
duplicating what tox already provides. Consolidating on tox as the
single task runner simplifies onboarding (one tool to install),
removes the custom setup_rye GitHub Action, and makes CI consistent
with local development workflows.

The test matrix now includes sphinx-needs as a third axis
(py{312,313,314}-sphinx{7,8,9}-needs{5,6,7,8}), enabling detection
of compatibility issues across the full support range. CI runs the
boundary combinations — minimal (py312-sphinx7-needs5) and maximal
(py314-sphinx8-needs8) — to catch regressions without excessive
job count.

- Remove [tool.rye] and [tool.rye.scripts] from pyproject.toml
- Delete .github/actions/setup_rye/ composite action
- Update CI workflows (ci, coverage, gh_pages) to use tox + tox-uv
- Add sphinx-needs version factors to tox.ini test environments
- Add tox demo environment replacing rye demo:clean chain
- Update AGENTS.md, contributing.rst, and demo README

Author: chrisjsewell

.github/actions/setup_rye/action.yml

@@ -37,36 +37,63 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup_rye
-      - run: rye run mypy:all
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - run: python -m pip install tox tox-uv
+      - run: tox -e mypy
 
   pytest:
-    name: Pytest (${{ matrix.os }})
+    name: "Pytest: ${{ matrix.tox-env }} (${{ matrix.os }})"
     strategy:
       fail-fast: false
       matrix:
         include:
+          # minimal versions
           - os: ubuntu-latest
+            python: "3.12"
+            tox-env: py312-sphinx7-needs5
+          # maximal versions
+          - os: ubuntu-latest
+            python: "3.14"
+            tox-env: py314-sphinx8-needs8
+          # minimal version on Windows
+          - os: windows-latest
+            python: "3.14"
+            tox-env: py312-sphinx7-needs5
+          # maximal versions on other OSes
           - os: ubuntu-24.04-arm
+            python: "3.14"
+            tox-env: py314-sphinx8-needs8
           - os: windows-latest
+            python: "3.14"
+            tox-env: py314-sphinx8-needs8
           - os: macos-latest
+            python: "3.14"
+            tox-env: py314-sphinx8-needs8
 
-    runs-on: ["${{ matrix.os }}"]
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup_rye
-      - run: rye test -a
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python }}"
+          allow-prereleases: true
+      - run: python -m pip install tox tox-uv
+      - run: tox -e "${{ matrix.tox-env }}"
 
   docs:
     name: Documentation build
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup_rye
-      - name: Run documentation build
-        run: rye run docs
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - run: python -m pip install tox tox-uv
+      - run: tox -e docs-clean
 
   all_good:
     # This job does nothing and is only used for the branch protection

.github/workflows/ci.yml

@@ -12,12 +12,14 @@ jobs:
 
       - name: Set up Python
         uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
 
-      - name: Setup rye
-        uses: ./.github/actions/setup_rye
+      - name: Install tox
+        run: python -m pip install tox tox-uv
 
       - name: Run tests
-        run: rye test -a -- --cov --cov-branch --cov-report=xml
+        run: tox -e py312-sphinx8-needs5 -- --cov --cov-branch --cov-report=xml
 
       - name: Upload results to Codecov
         uses: codecov/codecov-action@v5

.github/workflows/coverage.yaml

@@ -31,10 +31,12 @@ jobs:
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
-      - uses: eifinger/setup-rye@v4
-      - run: rye sync
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+      - run: python -m pip install tox tox-uv
       - name: Run documentation build
-        run: rye run docs
+        run: tox -e docs-clean
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/gh_pages.yml

@@ -1,3 +1,5 @@
+.DS_Store
+
 # python generated files
 .ruff_cache
 .pytest_cache
@@ -17,7 +19,7 @@ requirements-dev.lock
 # Sphinx build output
 **/_build
 
-# rye is the primary tool, uv is only used for on-the-fly setups
+# uv lock file
 uv.lock
 
 # coverage files
@@ -26,3 +28,5 @@ coverage.xml
 invalid_objs.json
 
 .tox
+
+output/

.gitignore

@@ -67,24 +67,27 @@ All commands should be run via [`tox`](https://tox.wiki) for consistency. The pr
 
 ### Testing
 
+Test environments follow the pattern `py{VERSION}-sphinx{MAJOR}-needs{MAJOR}`,
+e.g. `py312-sphinx8-needs5`. Use `tox -a` to list all available combinations.
+
 ```bash
 # Run default test environment
 tox
 
-# Run tests for specific Python/Sphinx combination
-tox -e py312-sphinx8
+# Run tests for a specific Python/Sphinx/sphinx-needs combination
+tox -e py312-sphinx8-needs5
 
 # Run a specific test file
-tox -e py312-sphinx8 -- tests/test_analyse.py
+tox -e py312-sphinx8-needs5 -- tests/test_analyse.py
 
 # Run a specific test function
-tox -e py312-sphinx8 -- tests/test_analyse.py::test_function_name
+tox -e py312-sphinx8-needs5 -- tests/test_analyse.py::test_function_name
 
 # Run with coverage
-tox -e py312-sphinx8 -- --cov=sphinx_codelinks
+tox -e py312-sphinx8-needs5 -- --cov=sphinx_codelinks
 
 # Update snapshot test fixtures
-tox -e py312-sphinx8 -- --snapshot-update
+tox -e py312-sphinx8-needs5 -- --snapshot-update
 ```
 
 ### Documentation
@@ -385,10 +388,10 @@ The CLI uses Typer for command definitions:
 
 ## Debugging
 
-- Use `--pdb` with pytest to drop into debugger on failures: `tox -e py312-sphinx8 -- --pdb`
-- Use `-v` for verbose test output: `tox -e py312-sphinx8 -- -v`
+- Use `--pdb` with pytest to drop into debugger on failures: `tox -e py312-sphinx8-needs5 -- --pdb`
+- Use `-v` for verbose test output: `tox -e py312-sphinx8-needs5 -- -v`
 - Build docs with `-T` flag for full tracebacks: `tox -e docs-clean -- -T`
-- Set logging level in tests: `tox -e py312-sphinx8 -- --log-cli-level=DEBUG`
+- Set logging level in tests: `tox -e py312-sphinx8-needs5 -- --log-cli-level=DEBUG`
 - Use `debug.py` module functions for development debugging
 
 ## Common Patterns

AGENTS.md

@@ -3,6 +3,11 @@
 Changelog
 =========
 
+Upcoming
+--------
+
+- ⬆️ Support and test sphinx-needs v5-8
+
 .. _`release:1.2.0`:
 
 1.2.0

docs/source/development/change_log.rst

@@ -22,13 +22,14 @@ Your PR should conform with the following rules:
 Install Dependencies
 --------------------
 
-``CodeLinks`` uses `rye <https://rye.astral.sh/>`_ to manage the repository.
+``CodeLinks`` uses `tox <https://tox.wiki/>`_ (with `tox-uv <https://github.com/tox-dev/tox-uv>`_) to manage development tasks.
 
-For development, use the following command to install Python dependencies into the virtual environment.
+Install tox with pip or uv:
 
 .. code-block:: bash
 
-   rye sync
+   pip install tox tox-uv
+   uv tool install tox --with tox-uv
 
 Formatting, Linting and Typing
 ------------------------------
@@ -44,7 +45,7 @@ The CI also checks typing. Use the following command locally to see if your code
 
 .. code-block:: bash
 
-   rye run mypy:all
+   tox -e mypy
 
 Build docs
 ----------
@@ -53,7 +54,7 @@ To build the documentation stored in ``docs``, run:
 
 .. code-block:: bash
 
-   rye run docs
+   tox -e docs-clean
 
 Test Cases
 ----------
@@ -62,7 +63,7 @@ To run test cases locally:
 
 .. code-block:: bash
 
-   rye test -a
+   tox -e py312-sphinx8
 
 Note some tests use `syrupy <https://github.com/tophat/syrupy>`__ to perform snapshot testing.
 These snapshots can be updated by running:

docs/source/development/contributing.rst

@@ -17,7 +17,7 @@ dependencies = [
   "click < 8.2",                # click 8.2.* produces empty errors if no args are given
   "jsonschema",
   "sphinx>=7.4,<9",
-  "sphinx-needs>=4.2.0",        # unconstrained versions, to be pinned by user or Sphinx
+  "sphinx-needs>=5,<9",
   "jinja2",
   "pygments",
   "docutils",                   # constrained by user or Sphinx
@@ -66,64 +66,9 @@ mypy = [
 ruff = ["ruff>=0.8.0"]
 build = ["simple-build>=0.0.2", "shiv>=1.0.8"]
 
-[tool.rye]
-managed = true
-dev-dependencies = [
-  "types-docutils",
-  "types-Pygments",
-  "syrupy>=4.9.1",
-  "furo>=2024.5.6",
-  "moto ~= 5.0",
-  "mypy>=1.12.1",
-  "myst-parser>=4.0.0",
-  "pydantic ~= 2.9",
-  "pip-licenses>=5.0.0",
-  "psutil>=7.0.0",
-  "pytest-cov>=5.0.0",
-  "pytest>=8.2.2",
-  "simple-build>=0.0.2",
-  "sphinx-design>=0.6.1",
-  "types-psutil>=7.0.0.20250218",
-  "uv>=0.5.5",
-  "pytest-docker>=3.1.2",
-  "shiv>=1.0.8",
-  "insta-science>=0.2.1",
-  "types-jsonschema>=4.23.0.20241208",
-  "toml>=0.10.2",
-  "sphinx-code-tabs>=0.5.5",
-  "sphinxcontrib-typer>=0.5.1",
-  "sphinxcontrib-video>=0.4.1",
-]
-
 [project.scripts]
 codelinks = "sphinx_codelinks.cmd:app"
 
-[tool.rye.scripts]
-# linting and formatting
-"mypy:all" = "mypy ."
-"rye:lint" = "rye lint"
-"rye:format" = "rye format"
-"check" = { chain = ["rye:format", "rye:lint", "mypy:all"] }
-# docs html
-"docs:rm" = "rm -rf docs/_build/html"
-"docs" = "sphinx-build -nW --keep-going -b html -T -c docs docs/source docs/_build/html"
-"docs:clean" = { chain = ["docs:rm", "docs"] }
-# needextend demo
-"analyse" = "codelinks analyse tests/data/configs/minimum_config.toml"
-"analyse:rm" = "rm -rf output/marked_content.json"
-"write" = "codelinks write rst output/marked_content.json --outpath tests/data/needextend_demo/needextend.rst"
-"write:rm" = "rm -rf tests/data/needextend_demo/needextend.rst"
-"demo:rm" = "rm -rf tests/data/needextend_demo/_build"
-"demo:build" = "sphinx-build -nW --keep-going -b html -T -c tests/data/needextend_demo tests/data/needextend_demo tests/data/needextend_demo/_build/html"
-"demo:clean" = { chain = [
-  "demo:rm",
-  "analyse:rm",
-  "write:rm",
-  "analyse",
-  "write",
-  "demo:build",
-] }
-
 [tool.ruff.lint]
 extend-select = [
   # "ANN",
@@ -162,15 +107,6 @@ force-sort-within-sections = true
   "PLR2004", # magic-value-comparison - valueable for tests
   "S101",    # assert - needed for tests
 ]
-"**/build_hooks_*/**" = [
-  "S607", # start-process-with-partial-path - pyarmor call in rye context
-  "S603", # subprocess-without-shell-equals-true - pyarmor call
-]
-"scripts/*.py" = [
-  "T201", # print - used for output
-  "S607", # start-process-with-partial-path - pyarmor call in rye context
-  "S603", # subprocess-without-shell-equals-true - build scripts
-]
 "src/sphinx_codelinks/sphinx_extension/debug.py" = [
   "T201",  # print - used for output
   "UP047", # on-pep695-generic-function - it's generic

pyproject.toml

@@ -3,5 +3,5 @@
 Run the following command in project root to have demo generated
 
 ```bash
-rye run demo:clean
+tox -e demo
 ```