docs(ext): Add sphinx-autodoc-pytest-fixtures demo page and extensions hub

why: The extension's badge system, fixture cards, and index tables need
a visual reference page for verifying rendering across themes and modes.
what:
- Add docs/extensions/ hub with grid cards for all workspace packages
- Add badge demo page with autofixture-index table and all badge
  permutations (scope, kind, autouse, deprecated, combinations)
- Add docs/_ext/spf_demo_fixtures.py with synthetic fixtures for demos
- Use eval-rst blocks for autofixture directives (autodoc generates RST
  that MyST cannot process as a native directive)
- Register sphinx_autodoc_pytest_fixtures as extra_extensions in conf.py
- Add extensions/index to docs toctree

Author: tony

docs/_ext/spf_demo_fixtures.py

@@ -0,0 +1,79 @@
+"""Synthetic fixtures for the sphinx_autodoc_pytest_fixtures badge demo page.
+
+Each fixture exercises one badge-slot combination so the demo page can show
+every permutation side-by-side:
+
+  Scope:  session | module | class | function (suppressed — no badge)
+  Kind:   resource (suppressed) | factory | override_hook
+  State:  autouse | deprecated (set via RST :deprecated: option)
+  Combos: session+factory, session+autouse
+
+These fixtures are purely for documentation; they are never collected by
+pytest during a real test run (the module is not in the test tree).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture
+def demo_plain() -> str:
+    """Plain function-scope resource. Shows FIXTURE badge only."""
+    return "plain"
+
+
+@pytest.fixture(scope="session")
+def demo_session() -> str:
+    """Session-scoped resource. Shows SESSION + FIXTURE badges."""
+    return "session"
+
+
+@pytest.fixture(scope="module")
+def demo_module() -> str:
+    """Module-scoped resource. Shows MODULE + FIXTURE badges."""
+    return "module"
+
+
+@pytest.fixture(scope="class")
+def demo_class() -> str:
+    """Class-scoped resource. Shows CLASS + FIXTURE badges."""
+    return "class"
+
+
+@pytest.fixture
+def demo_factory() -> type[str]:
+    """Return a callable (factory kind). Shows FACTORY + FIXTURE badges."""
+    return str
+
+
+@pytest.fixture
+def demo_override_hook() -> str:
+    """Override hook — customise in conftest.py. Shows OVERRIDE + FIXTURE badges."""
+    return "override"
+
+
+@pytest.fixture(autouse=True)
+def demo_autouse() -> None:
+    """Autouse fixture. Shows AUTO + FIXTURE badges."""
+
+
+@pytest.fixture
+def demo_deprecated() -> str:
+    """Return a value (deprecated since 1.0, replaced by demo_plain).
+
+    This fixture is documented with the ``deprecated`` RST option so the
+    demo page can show the DEPRECATED + FIXTURE badge combination.
+    """
+    return "deprecated"
+
+
+@pytest.fixture(scope="session")
+def demo_session_factory() -> type[str]:
+    """Session-scoped factory. Shows SESSION + FACTORY + FIXTURE badges."""
+    return str
+
+
+@pytest.fixture(scope="session", autouse=True)
+def demo_session_autouse() -> None:
+    """Session-scoped autouse. Shows SESSION + AUTO + FIXTURE badges."""

docs/conf.py

@@ -11,6 +11,10 @@
 sys.path.insert(0, str(project_root / "packages" / "gp-sphinx" / "src"))
 sys.path.insert(0, str(project_root / "packages" / "sphinx-fonts" / "src"))
 sys.path.insert(0, str(project_root / "packages" / "sphinx-gptheme" / "src"))
+sys.path.insert(
+    0, str(project_root / "packages" / "sphinx-autodoc-pytest-fixtures" / "src")
+)
+sys.path.insert(0, str(cwd / "_ext"))  # spf_demo_fixtures for badge demo
 
 import gp_sphinx  # noqa: E402
 from gp_sphinx.config import merge_sphinx_config  # noqa: E402
@@ -22,6 +26,8 @@
     source_repository=f"{gp_sphinx.__github__}/",
     docs_url=gp_sphinx.__docs__,
     source_branch="master",
+    extra_extensions=["sphinx_autodoc_pytest_fixtures"],
+    pytest_fixture_lint_level="none",
     rediraffe_redirects="redirects.txt",
     intersphinx_mapping={
         "py": ("https://docs.python.org/", None),

docs/extensions/index.md

@@ -0,0 +1,36 @@
+# Extensions
+
+Workspace packages that ship as independent Sphinx extensions.
+
+::::{grid} 1 1 2 2
+:gutter: 2 2 3 3
+
+:::{grid-item-card} sphinx-autodoc-pytest-fixtures
+:link: sphinx-autodoc-pytest-fixtures
+:link-type: doc
+Autodocumenter for pytest fixtures with scope badges, dependency
+tracking, and usage snippets.
+:::
+
+:::{grid-item-card} sphinx-fonts
+Self-hosted web fonts via Fontsource CDN with `@font-face` injection
+and preload hints.
+:::
+
+:::{grid-item-card} sphinx-gptheme
+Furo child theme with custom sidebar, SPA navigation, and IBM Plex
+typography.
+:::
+
+:::{grid-item-card} sphinx-argparse-neo
+Argparse CLI documentation with `.. argparse::` directive and epilog
+transformation.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+sphinx-autodoc-pytest-fixtures
+```

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

@@ -0,0 +1,109 @@
+# sphinx-autodoc-pytest-fixtures
+
+Sphinx extension that documents pytest fixtures as first-class domain objects
+with scope badges, dependency tracking, and auto-generated usage snippets.
+
+## Badge demo
+
+Visual reference for all badge permutations. Use this page to verify badge
+rendering across themes, zoom levels, and light/dark modes.
+
+```{py:module} spf_demo_fixtures
+```
+
+### Fixture index
+
+```{autofixture-index} spf_demo_fixtures
+```
+
+---
+
+### Plain (FIXTURE badge only)
+
+Function scope, resource kind, not autouse. Shows only the green FIXTURE badge.
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_plain
+```
+
+---
+
+### Scope badges
+
+#### Session scope
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_session
+```
+
+#### Module scope
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_module
+```
+
+#### Class scope
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_class
+```
+
+---
+
+### Kind badges
+
+#### Factory kind
+
+Return type `type[str]` is auto-detected as factory — no explicit `:kind:` needed.
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_factory
+```
+
+#### Override hook
+
+Requires explicit `:kind: override_hook` since it cannot be inferred from type.
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_override_hook
+   :kind: override_hook
+```
+
+---
+
+### State badges
+
+#### Autouse
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_autouse
+```
+
+#### Deprecated
+
+The `deprecated` badge is set via the `:deprecated:` RST option on `py:fixture`.
+
+```{eval-rst}
+.. py:fixture:: demo_deprecated
+   :deprecated: 1.0
+   :replacement: demo_plain
+   :return-type: str
+
+   Return a deprecated value. Use :fixture:`demo_plain` instead.
+```
+
+---
+
+### Combinations
+
+#### Session + Factory
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_session_factory
+```
+
+#### Session + Autouse
+
+```{eval-rst}
+.. autofixture:: spf_demo_fixtures.demo_session_autouse
+```

docs/index.md

@@ -51,6 +51,7 @@ globals().update(conf)
 :hidden:
 
 quickstart
+extensions/index
 project/index
 history
 ```