docs(widgets): introduce reusable widget framework + {mcp-install} picker

New in-tree Sphinx extension at docs/_ext/widgets/ that autodiscovers
BaseWidget subclasses and renders each via a Jinja2 template shipped
at docs/_widgets/<name>/widget.{html,js,css}. Assets are copied into
_static/widgets/<name>/ at build time and registered globally via
app.add_{css,js}_file.

First concrete widget is MCPInstallWidget (`{mcp-install}` directive).
It replaces the ~200-line nested sphinx-inline-tabs block in
quickstart.md with a single 5×3 client/method picker, and drops a
compact variant above the index.md grid. Tab state syncs across
widgets on the same page via CustomEvent, persists per-user via
localStorage, and survives gp-sphinx SPA navigation via document-
level event delegation + gp-sphinx:navigated listener.

Tests at tests/docs/test_widgets.py cover autodiscovery, the client×
method matrix, rendering, asset copy, missing-template handling,
option validation, and env.note_dependency tracking. Root conftest
registers sphinx.testing.fixtures so the Sphinx build fixtures are
available to pytest.

Author: tony

conftest.py

@@ -24,7 +24,7 @@
 if t.TYPE_CHECKING:
     import pathlib
 
-pytest_plugins = ["pytester"]
+pytest_plugins = ["pytester", "sphinx.testing.fixtures"]
 
 
 @pytest.fixture(autouse=True)

docs/_ext/widgets/__init__.py

@@ -0,0 +1,64 @@
+"""Reusable widget framework for Sphinx docs.
+
+Each widget is a ``BaseWidget`` subclass in a sibling module (e.g.
+``mcp_install.py``) plus a ``<docs>/_widgets/<name>/widget.{html,js,css}``
+asset directory. Widgets autodiscover at ``setup()`` time — adding a new one
+requires no registry edits. Usage from Markdown/RST:
+
+.. code-block:: markdown
+
+   ```{mcp-install}
+   :variant: compact
+   ```
+"""
+
+from __future__ import annotations
+
+import functools
+import typing as t
+
+from ._assets import install_widget_assets
+from ._base import (
+    BaseWidget,
+    depart_widget_container,
+    visit_widget_container,
+    widget_container,
+)
+from ._directive import make_widget_directive
+from ._discovery import discover
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseWidget",
+    "__version__",
+    "setup",
+    "widget_container",
+]
+
+
+def setup(app: Sphinx) -> dict[str, t.Any]:
+    """Register every discovered widget and wire the asset pipeline."""
+    widgets = discover()
+
+    app.add_node(
+        widget_container,
+        html=(visit_widget_container, depart_widget_container),
+    )
+
+    for name, widget_cls in widgets.items():
+        app.add_directive(name, make_widget_directive(widget_cls))
+
+    app.connect(
+        "builder-inited",
+        functools.partial(install_widget_assets, widgets=widgets),
+    )
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_ext/widgets/_assets.py

@@ -0,0 +1,51 @@
+"""Copy widget assets into ``_static/widgets/<name>/`` and register them."""
+
+from __future__ import annotations
+
+import pathlib
+import typing as t
+
+from sphinx.util import logging
+from sphinx.util.fileutil import copy_asset_file
+
+from ._base import BaseWidget
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+logger = logging.getLogger(__name__)
+
+STATIC_SUBDIR = "widgets"
+
+
+def install_widget_assets(
+    app: Sphinx,
+    widgets: dict[str, type[BaseWidget]],
+) -> None:
+    """Copy each widget's ``widget.{css,js}`` into ``_static/widgets/<name>/``.
+
+    Assets are then registered via ``app.add_css_file`` / ``app.add_js_file`` so
+    every page includes them (same pattern as ``sphinx-copybutton``). This is
+    intentionally simpler than per-page inclusion — the files are small and the
+    docs are not bandwidth-constrained.
+    """
+    if app.builder.format != "html":
+        return
+
+    srcdir = pathlib.Path(app.srcdir)
+    outdir_static = pathlib.Path(app.outdir) / "_static" / STATIC_SUBDIR
+
+    for name, widget_cls in widgets.items():
+        asset_dir = widget_cls.assets_dir(srcdir)
+        dest = outdir_static / name
+
+        for filename, register in (
+            ("widget.css", app.add_css_file),
+            ("widget.js", app.add_js_file),
+        ):
+            source = asset_dir / filename
+            if not source.is_file():
+                continue
+            dest.mkdir(parents=True, exist_ok=True)
+            copy_asset_file(str(source), str(dest))
+            register(f"{STATIC_SUBDIR}/{name}/{filename}")

docs/_ext/widgets/_base.py

@@ -0,0 +1,100 @@
+"""Base class for widgets and the docutils node that wraps rendered output."""
+
+from __future__ import annotations
+
+import abc
+import collections.abc
+import pathlib
+import typing as t
+
+import jinja2
+from docutils import nodes
+
+if t.TYPE_CHECKING:
+    from sphinx.environment import BuildEnvironment
+    from sphinx.writers.html5 import HTML5Translator
+
+
+class widget_container(nodes.container):  # type: ignore[misc]  # docutils nodes are untyped
+    """Wraps a widget's rendered HTML; visit/depart emit the outer div."""
+
+
+def visit_widget_container(
+    translator: HTML5Translator,
+    node: widget_container,
+) -> None:
+    """Open ``<div class="lm-widget lm-widget-{name}">`` for the widget."""
+    name = node["widget_name"]
+    translator.body.append(
+        f'<div class="lm-widget lm-widget-{name}" data-widget="{name}">'
+    )
+
+
+def depart_widget_container(
+    translator: HTML5Translator,
+    node: widget_container,
+) -> None:
+    """Close the widget wrapper div."""
+    translator.body.append("</div>")
+
+
+ASSET_FILES: tuple[str, ...] = ("widget.html", "widget.js", "widget.css")
+
+
+class BaseWidget(abc.ABC):
+    """Base class every concrete widget subclasses.
+
+    Subclasses declare ``name`` plus optional ``option_spec`` / ``default_options``
+    and may override ``context(env)`` to feed data into the Jinja template.
+    Assets (``widget.html``, ``widget.js``, ``widget.css``) live at
+    ``<srcdir>/_widgets/<name>/``; only ``widget.html`` is required.
+    """
+
+    name: t.ClassVar[str]
+    option_spec: t.ClassVar[
+        collections.abc.Mapping[str, collections.abc.Callable[[str], t.Any]]
+    ] = {}
+    default_options: t.ClassVar[collections.abc.Mapping[str, t.Any]] = {}
+
+    @classmethod
+    def assets_dir(cls, srcdir: pathlib.Path) -> pathlib.Path:
+        return srcdir / "_widgets" / cls.name
+
+    @classmethod
+    def template_path(cls, srcdir: pathlib.Path) -> pathlib.Path:
+        return cls.assets_dir(srcdir) / "widget.html"
+
+    @classmethod
+    def has_asset(cls, srcdir: pathlib.Path, filename: str) -> bool:
+        return (cls.assets_dir(srcdir) / filename).is_file()
+
+    @classmethod
+    def context(cls, env: BuildEnvironment) -> collections.abc.Mapping[str, t.Any]:
+        """Return extra Jinja context. Override in subclasses for widget data."""
+        return {}
+
+    @classmethod
+    def render(
+        cls,
+        *,
+        options: collections.abc.Mapping[str, t.Any],
+        env: BuildEnvironment,
+    ) -> str:
+        """Render the Jinja template with merged context, return HTML."""
+        template_path = cls.template_path(pathlib.Path(env.srcdir))
+        source = template_path.read_text(encoding="utf-8")
+        jenv = jinja2.Environment(
+            undefined=jinja2.StrictUndefined,
+            autoescape=jinja2.select_autoescape(["html"]),
+            keep_trailing_newline=False,
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+        template = jenv.from_string(source)
+        context: dict[str, t.Any] = {
+            **cls.default_options,
+            **options,
+            **cls.context(env),
+            "widget_name": cls.name,
+        }
+        return template.render(**context)

docs/_ext/widgets/_directive.py

@@ -0,0 +1,65 @@
+"""Factory that manufactures a Sphinx Directive class for a given widget."""
+
+from __future__ import annotations
+
+import pathlib
+import typing as t
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+from ._base import ASSET_FILES, BaseWidget, widget_container
+
+
+def make_widget_directive(widget_cls: type[BaseWidget]) -> type[SphinxDirective]:
+    """Create a ``SphinxDirective`` subclass bound to ``widget_cls``.
+
+    Each widget gets its own Directive subclass (not a single dispatcher) because
+    docutils parses ``:option:`` lines against ``option_spec`` *before* calling
+    ``run()`` -- so the spec must be static per directive name.
+    """
+
+    class _WidgetDirective(SphinxDirective):
+        has_content = False
+        required_arguments = 0
+        optional_arguments = 0
+        final_argument_whitespace = False
+        # Copy the widget's option_spec so per-directive mutations don't leak.
+        option_spec: t.ClassVar[dict[str, t.Any]] = dict(widget_cls.option_spec)
+
+        def run(self) -> list[nodes.Node]:
+            """Render the widget and return a single ``widget_container`` node."""
+            merged: dict[str, t.Any] = {
+                **widget_cls.default_options,
+                **self.options,
+            }
+            self._note_asset_dependencies()
+            html = self._render(merged)
+            container = widget_container(widget_name=widget_cls.name)
+            container += nodes.raw("", html, format="html")
+            self.set_source_info(container)
+            return [container]
+
+        def _render(self, options: dict[str, t.Any]) -> str:
+            try:
+                return widget_cls.render(options=options, env=self.env)
+            except FileNotFoundError as exc:
+                msg = (
+                    f"widget {widget_cls.name!r}: template not found -- "
+                    f"expected {exc.filename}"
+                )
+                raise self.severe(msg) from exc
+            except Exception as exc:  # Jinja UndefinedError, etc.
+                msg = f"widget {widget_cls.name!r} render failed: {exc}"
+                raise self.error(msg) from exc
+
+        def _note_asset_dependencies(self) -> None:
+            assets_dir = widget_cls.assets_dir(pathlib.Path(self.env.srcdir))
+            for filename in ASSET_FILES:
+                path = assets_dir / filename
+                if path.is_file():
+                    self.env.note_dependency(str(path))
+
+    _WidgetDirective.__name__ = f"{widget_cls.__name__}Directive"
+    _WidgetDirective.__qualname__ = _WidgetDirective.__name__
+    return _WidgetDirective

docs/_ext/widgets/_discovery.py

@@ -0,0 +1,46 @@
+"""Autodiscover widget classes from sibling modules in this package."""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+from ._base import BaseWidget
+
+
+def discover() -> dict[str, type[BaseWidget]]:
+    """Import every non-underscore submodule; collect ``BaseWidget`` subclasses.
+
+    Adding a new widget means: drop ``mywidget.py`` next to ``mcp_install.py`` with a
+    ``MyWidget(BaseWidget)`` that sets ``name = "mywidget"`` -- the discovery sweep
+    at ``setup()`` time registers it automatically.
+    """
+    from . import __name__ as pkg_name, __path__ as pkg_path
+
+    registry: dict[str, type[BaseWidget]] = {}
+    for info in pkgutil.iter_modules(pkg_path):
+        if info.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"{pkg_name}.{info.name}")
+        for obj in vars(module).values():
+            if not _is_widget_class(obj):
+                continue
+            existing = registry.get(obj.name)
+            if existing is not None and existing is not obj:
+                msg = (
+                    f"Duplicate widget name {obj.name!r}: "
+                    f"{existing.__module__} vs {obj.__module__}"
+                )
+                raise RuntimeError(msg)
+            registry[obj.name] = obj
+    return registry
+
+
+def _is_widget_class(obj: object) -> bool:
+    """Return True iff ``obj`` is a concrete ``BaseWidget`` subclass with a name."""
+    return (
+        isinstance(obj, type)
+        and issubclass(obj, BaseWidget)
+        and obj is not BaseWidget
+        and getattr(obj, "name", None) is not None
+    )