Add a doctest CI run

Author: dstansby

.github/workflows/test.yml

@@ -94,13 +94,36 @@ jobs:
       run: |
         hatch env run --env ${{ matrix.dependency-set }} run
 
+  doctests:
+    name: doctests
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+        cache: 'pip'
+    - name: Install Hatch
+      run: |
+        python -m pip install --upgrade pip
+        pip install hatch
+    - name: Set Up Hatch Env
+      run: |
+        hatch env create doctest
+        hatch env run -e doctest list-env
+    - name: Run Tests
+      run: |
+        hatch env run --env doctest run
+
   test-complete:
     name: Test complete
 
     needs:
       [
         test,
         test-upstream-and-min-deps,
+        doctests
       ]
     if: always()
     runs-on: ubuntu-latest
@@ -111,4 +134,4 @@ jobs:
           contains(needs.*.result, 'cancelled')
         run: exit 1
       - name: Success
-        run: echo Success!
+        run: echo Success!

pyproject.toml

@@ -138,14 +138,22 @@ numpy = ["1.25", "2.1"]
 features = ["gpu"]
 
 [tool.hatch.envs.test.scripts]
-run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=src --doctest-glob='*.rst'"
+run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=src"
 run-coverage-gpu = "pip install cupy-cuda12x && pytest -m gpu --cov-config=pyproject.toml --cov=pkg --cov=src"
 run = "run-coverage --no-cov"
 run-verbose = "run-coverage --verbose"
 run-mypy = "mypy src"
 run-hypothesis = "pytest --hypothesis-profile ci tests/test_properties.py tests/test_store/test_stateful*"
 list-env = "pip list"
 
+[tool.hatch.envs.doctest]
+features = ["test", "optional"]
+description = "Test environment for doctests"
+
+[tool.hatch.envs.doctest.scripts]
+run = "pytest docs/user-guide --doctest-glob='*.rst'"
+list-env = "pip list"
+
 [tool.hatch.envs.gputest]
 dependencies = [
     "numpy~={matrix:numpy}",
@@ -351,7 +359,7 @@ ignore_errors = true
 
 [tool.pytest.ini_options]
 minversion = "7"
-testpaths = ["tests", "docs"]
+testpaths = ["tests", "docs/user-guide"]
 log_cli_level = "INFO"
 xfail_strict = true
 asyncio_mode = "auto"