doctest_core: typed doctest core architecture spike

.github/workflows/tests.yml

@@ -7,23 +7,20 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
 
     runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
     strategy:
       matrix:
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
-        docutils-version: ['0.20', '0.22.4']
-        pytest-version: ['8', '9']
-        exclude:
-          # docutils 0.22 removed the bundled docutils.utils.roman. Sphinx 8.1
-          # imports it, so its latex builder fails to load. Sphinx 8.2 dropped
-          # that import but requires Python 3.11, and 8.1 is the newest release
-          # supporting 3.10, leaving no working pair on that interpreter.
-          - python-version: '3.10'
-            docutils-version: '0.22.4'
-    # Overrides the repo's .python-version so every uv command in this job
-    # uses the matrix interpreter. `uv python install` only downloads one;
-    # without this the environment is built against .python-version instead.
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
+        docutils-version: ['0.20.1', '0.21.2']
+        pytest-version: ['8.4.2', '9.1.1']
+        include:
+          - pytest-version: '8.4.2'
+            pytest-asyncio-version: '1.4.0'
+            pytest-rerunfailures-version: '16.4'
+          - pytest-version: '9.1.1'
+            pytest-asyncio-version: '1.4.0'
+            pytest-rerunfailures-version: '16.4'
     steps:
       - uses: actions/checkout@v7
 
@@ -41,11 +38,16 @@ jobs:
       # Every step below runs --no-sync. A plain `uv run` re-syncs the
       # environment to uv.lock first, which would undo these pins and run
       # every matrix leg against the locked versions.
-      - name: Install matrix pytest and docutils
+      - name: Install matrix versions
         run: >-
           uv pip install
-          "pytest~=${{ matrix.pytest-version }}.0"
           "docutils==${{ matrix.docutils-version }}"
+          "pytest==${{ matrix.pytest-version }}"
+          "pytest-asyncio==${{ matrix.pytest-asyncio-version }}"
+          "pytest-rerunfailures==${{ matrix.pytest-rerunfailures-version }}"
+
+      - name: Check dependency consistency
+        run: uv pip check
 
       - name: Print python, pytest and docutils versions
         run: |

README.md

@@ -12,9 +12,10 @@ git-pull projects, e.g. [cihai], [vcs-python], or [tmux-python].
 
 Two components:
 
-1. `doctest_docutils` module: Same specification as `doctest`, but can parse reStructuredText
-   and markdown
-2. `pytest_doctest_docutils`: Pytest plugin, collects test items for pytest for reStructuredText and markdown files
+1. `doctest_docutils`: a doctest-shaped direct API and CLI for reStructuredText
+   and Markdown
+2. `pytest_doctest_docutils`: a pytest plugin that collects shared-state groups
+   from reStructuredText and Markdown files
 
    This means you can do:
 
@@ -24,8 +25,8 @@ Two components:
 
 ### doctest module
 
-This extends standard library `doctest` to support anything docutils can parse.
-It can parse reStructuredText (.rst) and markdown (.md).
+This uses standard-library `doctest` prompt and comparison conventions while
+parsing reStructuredText (`.rst`) and Markdown (`.md`).
 
 See more: <https://gp-libs.git-pull.com/modules/doctest_docutils/>
 
@@ -64,7 +65,7 @@ It supports two barebones directives:
 
 #### Usage
 
-The `doctest_docutils` module preserves standard library's usage conventions:
+The `doctest_docutils` module preserves the standard library's command shape:
 
 ##### reStructuredText
 
@@ -84,10 +85,10 @@ $ python -m doctest_docutils README.md -v
 
 ### pytest plugin
 
-_This plugin disables [pytest's standard `doctest` plugin]._
-
-This plugin integrates `doctest_docutils` with pytest so documentation examples
-run with the surrounding `conftest.py` setup.
+This plugin runs documentation examples as pytest items. It composes with
+[pytest's standard `doctest` plugin]: gp-libs owns matching documentation files,
+while pytest continues to supply fixtures, checker and report options, and
+Python-module doctest collection.
 
 ```console
 $ pytest docs/
@@ -154,7 +155,7 @@ You can test the unpublished version of g before its released.
 To lift the development burden of supporting legacy APIs, as this package is
 lightly used, minimum constraints have been pinned:
 
-- docutils: 0.20.1+
+- docutils: >=0.20.1,<0.22
 - myst-parser: 2.0.0+
 
 If you have even passing interested in supporting legacy versions, file an