docs(pytest-plugin): Render fixture cards on /doctest/pytest/ via sphinx_autodoc_pytest_fixtures

[tony]

The sphinx_autodoc_pytest_fixtures Sphinx extension shipped in gp-sphinx 0.0.1a18 is wired into docs/conf.py extra_extensions= and resolves cleanly during the build, but docs/doctest/pytest.md contains no .. autofixture:: or .. auto-pytest-plugin:: directives. The rendered /doctest/pytest/ page therefore has nothing fixture-shaped on it — visually it looks unchanged from the pre-extension state.

The canonical precedent

cihai/unihan-etl@a29d79e (docs(feat[pytest-plugin]) Curate fixture sections) is the model. unihan-etl's docs/api/pytest-plugin.md documents 29 shipped fixtures from unihan_etl.pytest_plugin grouped into seven curated sections (Quick Start → Which Fixture Do I Need → Dataset Bootstrap → Dataset Options & Paths → Raw Data Accessors → Mock Zip → Cache Paths → Home & Env → Function-Scoped Helpers → Types → Configuration → bulk autofixtures:: note). Each fixture is rendered with a scope badge, dependency list, and optional inline .. rubric:: Example code block.

Sibling precedents in the same gp-sphinx 0.0.1a18 cohort:

• libtmux: docs/api/testing/pytest-plugin/fixtures.md — same shape, individual .. autofixture:: per fixture across Core / Environment / Override Hooks / Factories / Low-Level sections, plus a top-level {autofixture-index} bulk view.
• libvcs: docs/api/pytest-plugin.md — uses a custom {doc-pytest-plugin} block plus hand-curated {fixture} cross-references instead of .. autofixture::. Different style, same goal.

Why this isn't a trivial copy-paste for gp-libs

The unihan-etl / libtmux pattern requires an importable pytest plugin module with @pytest.fixture decorators. A quick check:

$ grep -rn "@pytest.fixture\|@fixture" src/
(no matches)

src/pytest_doctest_docutils.py is a hook-only plugin (pytest_addoption, pytest_configure, pytest_collect_file). The only fixture-shaped helper in the repository is make_app_params in tests/conftest.py, which is not on the import path that Sphinx autodoc can reach.

Resolution paths

1. Ship make_app_params (closest to unihan-etl/libtmux)

Move make_app_params, AppParams, and MakeAppParams from tests/conftest.py to a new shipped module src/pytest_gp_libs.py. Register a second pytest11 entry point:

[project.entry-points.pytest11]
sphinx = \"pytest_doctest_docutils\"
gp_libs = \"pytest_gp_libs\"

Then docs/doctest/pytest.md can be rewritten in the unihan-etl shape: Quick Start → Which Fixture → one .. autofixture:: pytest_gp_libs.make_app_params (under a "Sphinx App" section) → Types (AppParams, MakeAppParams via autodata / autoclass) → Configuration → bulk-autofixtures note. One fixture rendered, but it renders properly and the extension does real work.

Trade-off: the pytest11 entry point auto-loads the fixture into every downstream consumer of gp-libs — including projects that don't load sphinx.testing.fixtures. The fixture itself never runs unless explicitly requested, and the import is safe (no sphinx-side imports at module top), so the practical blast radius is "downstream sees a make_app_params fixture appear in pytest --fixtures output and gets a clear 'fixture app_params not found' error if they request it without sphinx."

2. Skip autofixture:: entirely, write rich prose

Keep tests/conftest.py untouched. Rewrite docs/doctest/pytest.md to be a guide: an extended Quick Start, an options reference via .. confval:: (the existing --doctest-docutils-modules / --no-doctest-docutils-modules flags from src/pytest_doctest_docutils.py:47-62), a worked doctest_namespace example mirroring libtmux's tests/conftest.py pattern. The extension stays loaded but unused.

3. .. auto-pytest-plugin:: pytest_doctest_docutils

Point the directive at the existing hook-only module. Likely renders nothing or near-nothing — AutoPytestPluginDirective discovers fixtures, of which there are none. Worth trying as a diagnostic, but probably a dead end on its own.

Related work

• PR #NN (this draft) wires the extension and switches gp-libs' own pytest config to dogfood --doctest-docutils-modules. The docs content gap is intentionally deferred to this issue.

Suggested next step

Decide between paths 1 and 2 before authoring further docs. Path 1 produces the same shape as the rest of the ecosystem at the cost of a small new public API surface. Path 2 keeps gp-libs zero-surface but produces a different-looking page than libtmux/unihan-etl/libvcs.