feat(pytest-plugin): Add doc-pytest-plugin directive (#8)

Adds a higher-level `doc-pytest-plugin` directive to
`sphinx-autodoc-pytest-fixtures` for building standard pytest plugin
documentation pages. The directive generates a consistent frame —
install block, `pytest11` autodiscovery note, fixture summary and
reference — owned in one place so the prose propagates to every
downstream build automatically.

- **New directive** `doc-pytest-plugin`: required `:package:`,
  optional `:project:`, `:summary:`, `:tests-url:`, and
  `:install-command:`. Body content is free-form (sections,
  prose, code blocks); the frame is opinionated. Use the manual
  `autofixture-index` + `autofixtures` recipe when custom layout
  or section ordering is needed ("power path").
- **Removed** `:mode:` — `reference` mode duplicated the manual
  recipe, undermining the abstraction.
- **Relaxed** `:summary:` and `:project:` to optional. Missing
  `:summary:` suppresses the intro paragraph (no empty `<p>`).
  Missing `:project:` falls back to generic "test suite" link
  text; the package-slug default was a deliberate non-option.
- **Fixed** `NameError` crash in `_build_fixture_section_nodes`:
  `_build_doc_pytest_plugin_index_node` had been removed but its
  call site was not updated, crashing every docs build.
- **Fixed** `sphinx-build -W` docs warnings: replaced
  `_is_markdown_source` (file-extension check) with
  `_is_native_myst` (`isinstance(state, MockState)`) so directives
  inside `{eval-rst}` blocks are not wrapped in a backtick fence
  before being passed to RST's `nested_parse`.
- **Added** `:no-index:` flag to `autofixtures::` for pages that
  describe the same module in multiple sections.
- **Tests**: coverage for generic `:project:` link text, optional
  `:summary:`, and hard failure on missing `:package:`.
- **Docs**: "When to use" and "Manual recipe" sections added.

Author: tony

CHANGES

@@ -34,6 +34,11 @@ $ uv add gp-sphinx --prerelease allow
   badges, classified dependency lists, reverse-dep tracking, and auto-generated
   usage snippets. Frozen dataclasses for pickle-safe incremental builds, parallel-safe,
   WCAG AA badge contrast, and pytest 9+ compatible.
+  New: `doc-pytest-plugin` directive generates a standard pytest plugin page
+  (install block, `pytest11` autodiscovery note, fixture summary and reference)
+  from a single directive call. Optional `:project:`, `:summary:`, `:tests-url:`,
+  and `:install-command:` options; body is free-form. Use `autofixture-index` +
+  `autofixtures` directly when custom layout is needed.
 - `sphinx-fonts` — Self-hosted web fonts via Fontsource CDN. Downloads at build time,
   caches locally, and injects `@font-face` CSS with preload hints and fallback
   font-metric overrides for zero-CLS loading.

docs/packages/sphinx-autodoc-pytest-fixtures.md

@@ -4,7 +4,8 @@
 
 Sphinx extension for documenting pytest fixtures as first-class objects. It
 registers a Python-domain fixture directive and role, autodoc helpers for bulk
-fixture discovery, and the badge/index UI used throughout the page below.
+fixture discovery, a higher-level pytest plugin page helper, and the
+badge/index UI used throughout the page below.
 
 ```console
 $ pip install sphinx-autodoc-pytest-fixtures
@@ -49,14 +50,49 @@ pytest_external_fixture_links = {
 
 ```{eval-rst}
 .. autofixtures:: spf_demo_fixtures
+   :no-index:
+```
+
+### Plugin page helper
+
+:::{doc-pytest-plugin} spf_demo_fixtures
+:package: sphinx-autodoc-pytest-fixtures
+
+Add project-specific usage notes here. The helper renders the install
+section, autodiscovery note, and full fixture summary/reference.
+:::
+
+#### When to use `doc-pytest-plugin`
+
+Use this directive for a standard pytest plugin page where you want consistent
+house-style: an install section, the `pytest11` autodiscovery note, and a
+generated fixture summary and reference.
+
+#### Manual recipe (power path)
+
+When you need custom layout — a different section order, content between the
+summary and reference, or no install block — use the low-level directives
+directly:
+
+````markdown
+## Fixture Summary
+
+```{autofixture-index} libvcs.pytest_plugin
+```
+
+## Fixture Reference
+
+```{autofixtures} libvcs.pytest_plugin
 ```
+````
 
 #### autofixtures options
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `:order:` | `"source"` | `"source"` preserves module order; `"alpha"` sorts alphabetically |
 | `:exclude:` | (empty) | Comma-separated fixture names to skip |
+| `:no-index:` | (off) | Emit descriptions without registering fixtures in the domain index; use when the same module is documented twice on one page |
 
 #### autofixture-index options
 

packages/sphinx-autodoc-pytest-fixtures/README.md

@@ -24,6 +24,12 @@ Then document fixtures with:
 .. autofixtures:: myproject.conftest
 
 .. autofixture-index:: myproject.conftest
+
+.. doc-pytest-plugin:: myproject.pytest_plugin
+   :project: myproject
+   :package: myproject
+   :summary: Document your pytest plugin with generated install and fixture
+      reference sections.
 ```
 
 ## Documentation

packages/sphinx-autodoc-pytest-fixtures/src/sphinx_autodoc_pytest_fixtures/__init__.py

@@ -53,6 +53,7 @@
 from sphinx_autodoc_pytest_fixtures._directives import (
     AutofixtureIndexDirective,
     AutofixturesDirective,
+    DocPytestPluginDirective,
     PyFixtureDirective,
 )
 from sphinx_autodoc_pytest_fixtures._documenter import FixtureDocumenter
@@ -174,6 +175,7 @@ def _add_static_path(app: Sphinx) -> None:
     app.add_directive("autofixtures", AutofixturesDirective)
     app.add_node(autofixture_index_node)
     app.add_directive("autofixture-index", AutofixtureIndexDirective)
+    app.add_directive("doc-pytest-plugin", DocPytestPluginDirective)
 
     app.connect("missing-reference", _on_missing_reference)
     app.connect("doctree-resolved", _on_doctree_resolved)