pkg(sphinx-autodoc-pytest-fixtures[feat]): gate auto-pytest-plugin fixture-index behind :fixture-index: flag

why: ``auto-pytest-plugin`` always emitted a "Fixture Summary" rubric +
:class:\`autofixture_index_node\` placeholder before the "Fixture
Reference" detail blocks. For pytest plugin pages where the detail
blocks already render every fixture's name, scope, return type, and
description, the summary table is duplicative — Furo's ToC sidebar
already enumerates each ``:fixture:`` anchor by name.

what:
- Add ``:fixture-index:`` flag option to ``AutoPytestPluginDirective``.
  Default unset → no summary. Pass ``:fixture-index:`` to opt back in
  for dense plugin pages that genuinely benefit from a scan-all view.
- ``_build_doc_pytest_plugin_fixture_section_scaffold(modname,
  include_index=False)`` is the new pure helper signature; the
  fixture-summary rubric and placeholder render only when ``include_index``
  is ``True``.
- ``_build_fixture_section_nodes`` forwards the flag.
- Existing ``test_..._scaffold_sets_module`` and
  ``test_..._scaffold_contains_index_node`` updated to pass
  ``include_index=True`` (preserving their original assertions).
- New ``test_..._scaffold_defaults_to_no_summary`` covers the default
  off path.
- Two integration scenarios in ``test_sphinx_pytest_fixtures_doctree.py``
  (``myst_smoke_result`` fixture + ``test_doc_pytest_plugin_rst_snapshot``)
  exercise the summary path explicitly — now pass
  ``:fixture-index:`` so they continue to assert "Fixture Summary"
  appears in the output.

Author: tony

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

@@ -218,16 +218,33 @@ def _build_doc_pytest_plugin_intro_nodes(
 
 def _build_doc_pytest_plugin_fixture_section_scaffold(
     modname: str,
+    *,
+    include_index: bool = False,
 ) -> list[nodes.Node]:
-    """Return the generated fixture-section scaffold nodes."""
-    idx_node = autofixture_index_node()
-    idx_node["module"] = modname
-    idx_node["exclude"] = set()
-    return [
-        nodes.rubric("", "Fixture Summary"),
-        idx_node,
-        nodes.rubric("", "Fixture Reference"),
-    ]
+    """Return the generated fixture-section scaffold nodes.
+
+    Parameters
+    ----------
+    modname : str
+        Module the fixture-index placeholder targets.
+    include_index : bool, optional
+        When ``True``, prefix the section with a "Fixture Summary" rubric
+        and an :class:`autofixture_index_node` placeholder before the
+        "Fixture Reference" detail block.  Defaults to ``False`` because
+        Furo's ToC sidebar already enumerates each ``:fixture:`` anchor
+        — the summary table only adds value on dense plugin pages where
+        a scan-all-options view is desired.  Toggle on via the
+        ``:fixture-index:`` flag on ``auto-pytest-plugin``.
+    """
+    section_nodes: list[nodes.Node] = []
+    if include_index:
+        idx_node = autofixture_index_node()
+        idx_node["module"] = modname
+        idx_node["exclude"] = set()
+        section_nodes.append(nodes.rubric("", "Fixture Summary"))
+        section_nodes.append(idx_node)
+    section_nodes.append(nodes.rubric("", "Fixture Reference"))
+    return section_nodes
 
 
 def _compose_doc_pytest_plugin_nodes(
@@ -763,6 +780,7 @@ class AutoPytestPluginDirective(SphinxDirective):
         "summary": directives.unchanged,
         "tests-url": directives.unchanged,
         "install-command": directives.unchanged,
+        "fixture-index": directives.flag,
     }
 
     def run(self) -> list[nodes.Node]:
@@ -795,6 +813,7 @@ def run(self) -> list[nodes.Node]:
             fixture_section_nodes = self._build_fixture_section_nodes(
                 modname=modname,
                 entries=entries,
+                include_index="fixture-index" in self.options,
             )
 
         return _compose_doc_pytest_plugin_nodes(
@@ -859,10 +878,28 @@ def _build_fixture_section_nodes(
         *,
         modname: str,
         entries: list[tuple[str, str, t.Any]],
+        include_index: bool = False,
     ) -> list[nodes.Node]:
-        """Build generated fixture summary/reference nodes."""
+        """Build generated fixture summary/reference nodes.
+
+        Parameters
+        ----------
+        modname : str
+            Module containing the fixtures.
+        entries : list[tuple[str, str, Any]]
+            Discovered ``(public_name, attribute_name, fixture_fn)`` tuples.
+        include_index : bool, optional
+            Forwarded to
+            :func:`_build_doc_pytest_plugin_fixture_section_scaffold` —
+            controls whether the ``Fixture Summary`` rubric and
+            :class:`autofixture_index_node` placeholder render before the
+            detail blocks.  Defaults to ``False``.
+        """
         return [
-            *_build_doc_pytest_plugin_fixture_section_scaffold(modname),
+            *_build_doc_pytest_plugin_fixture_section_scaffold(
+                modname,
+                include_index=include_index,
+            ),
             *_render_autofixtures_nodes(
                 self,
                 modname=modname,

tests/ext/pytest_fixtures/test_sphinx_pytest_fixtures.py

@@ -172,9 +172,10 @@ def test_build_doc_pytest_plugin_intro_nodes_include_install_and_link() -> None:
 
 
 def test_build_doc_pytest_plugin_fixture_section_scaffold_sets_module() -> None:
-    """Fixture-section scaffold carries the target module on the placeholder."""
+    """``include_index=True`` adds a Fixture Summary rubric + index placeholder."""
     scaffold = spf_directives._build_doc_pytest_plugin_fixture_section_scaffold(
         "fixture_mod",
+        include_index=True,
     )
 
     assert [type(node) for node in scaffold] == [
@@ -188,6 +189,21 @@ def test_build_doc_pytest_plugin_fixture_section_scaffold_sets_module() -> None:
     assert scaffold[2].astext() == "Fixture Reference"
 
 
+def test_build_doc_pytest_plugin_fixture_section_scaffold_defaults_to_no_summary() -> (
+    None
+):
+    """Default ``include_index=False`` emits only the Fixture Reference rubric."""
+    scaffold = spf_directives._build_doc_pytest_plugin_fixture_section_scaffold(
+        "fixture_mod",
+    )
+
+    assert [type(node) for node in scaffold] == [nodes.rubric]
+    assert scaffold[0].astext() == "Fixture Reference"
+    assert not any(
+        isinstance(node, spf_directives.autofixture_index_node) for node in scaffold
+    )
+
+
 def test_compose_doc_pytest_plugin_nodes_preserves_display_order() -> None:
     """Intro, authored body, and fixture section nodes stay in display order."""
     intro_nodes = [nodes.paragraph("", "intro")]
@@ -1369,9 +1385,10 @@ def test_build_doc_pytest_plugin_intro_nodes_uses_generic_test_suite_text() -> N
 
 
 def test_build_doc_pytest_plugin_fixture_section_scaffold_contains_index_node() -> None:
-    """Fixture section scaffold is testable without parsing nested directives."""
+    """``include_index=True`` produces both rubrics + the index placeholder."""
     section_nodes = spf_directives._build_doc_pytest_plugin_fixture_section_scaffold(
-        "fixture_mod"
+        "fixture_mod",
+        include_index=True,
     )
 
     assert [
@@ -1380,6 +1397,10 @@ def test_build_doc_pytest_plugin_fixture_section_scaffold_contains_index_node()
         "Fixture Summary",
         "Fixture Reference",
     ]
+    assert isinstance(
+        section_nodes[1],
+        spf_directives.autofixture_index_node,
+    )
     assert isinstance(
         section_nodes[1],
         sphinx_autodoc_pytest_fixtures.autofixture_index_node,

tests/ext/pytest_fixtures/test_sphinx_pytest_fixtures_doctree.py

@@ -171,6 +171,7 @@ def myst_smoke_result(spf_doctree_root: pathlib.Path) -> SharedSphinxResult:
                     :package: fixture-demo
                     :summary: fixture-demo ships a pytest plugin for local test setup.
                     :tests-url: https://example.com/fixture-demo/tests
+                    :fixture-index:
 
                     ## Recommended fixtures
 
@@ -588,6 +589,7 @@ def test_doc_pytest_plugin_rst_snapshot(
            :summary: fixture-demo ships a pytest plugin for local test setup.
            :tests-url: https://example.com/fixture-demo/tests
            :install-command: uv add --dev fixture-demo
+           :fixture-index:
 
            Use the plugin when you want isolated test resources with minimal
            conftest boilerplate.