Implement the typed doctest core architecture

.github/workflows/tests.yml

@@ -7,15 +7,27 @@ 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.18', '0.19']
-        pytest-version: ['7', '8', '9']
+        docutils-version: ['0.20.1', '0.21.2']
+        pytest-version: ['7.2.0', '8.4.2', '9.1.1']
+        include:
+          - pytest-version: '7.2.0'
+            pytest-asyncio-version: '0.21.2'
+            pytest-rerunfailures-version: '13.0'
+          - 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'
         exclude:
-          # Exclude pytest 7 from Python 3.14 to reduce matrix size
+          # Pytest 7 does not support Python 3.14.
           - python-version: '3.14'
-            pytest-version: '7'
+            pytest-version: '7.2.0'
     steps:
       - uses: actions/checkout@v7
 
@@ -30,26 +42,34 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
-      - name: Install specific pytest version
-        run: uv pip install "pytest~=${{ matrix.pytest-version }}.0"
+      - name: Install matrix versions
+        run: >-
+          uv pip install
+          "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 and pytest versions
         run: |
           python -V
-          uv run python -V
-          uv run pytest --version
+          uv run --no-sync python -V
+          uv run --no-sync pytest --version
 
       - name: Lint with ruff check
-        run: uv run ruff check .
+        run: uv run --no-sync ruff check .
 
       - name: Format with ruff format
-        run: uv run ruff format . --check
+        run: uv run --no-sync ruff format . --check
 
       - name: Lint with mypy
-        run: uv run mypy .
+        run: uv run --no-sync mypy .
 
       - name: Test with pytest
-        run: uv run py.test --cov=./ --cov-report=xml
+        run: uv run --no-sync py.test --cov=./ --cov-report=xml
 
       - uses: codecov/codecov-action@v7
         with:

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