docs(refactor[widgets]): switch widget imports to docs._ext.widgets

why: Use one canonical module path for the docs widget extension so tools and tests resolve it consistently.
what:
- load the Sphinx extension via docs._ext.widgets
- put the repo root on sys.path for docs and widget tests
- update widget test imports to the canonical package path

Author: tony

docs/conf.py

@@ -19,8 +19,8 @@
 project_root = cwd.parent
 project_src = project_root / "src"
 
+sys.path.insert(0, str(project_root))
 sys.path.insert(0, str(project_src))
-sys.path.insert(0, str(cwd / "_ext"))
 
 # package data
 about: dict[str, str] = {}
@@ -40,7 +40,7 @@
         "sphinx_autodoc_api_style",
         "sphinx.ext.todo",
         "sphinx_autodoc_fastmcp",
-        "widgets",
+        "docs._ext.widgets",
     ],
     intersphinx_mapping={
         "python": ("https://docs.python.org/", None),

tests/docs/conftest.py

@@ -1,9 +1,9 @@
 """pytest config for widget tests: wire Sphinx's test fixtures + path.
 
 ``sphinx.testing.fixtures`` provides ``make_app``, ``app``, etc. that build a
-throw-away Sphinx project in a tmp dir. We also add ``docs/_ext`` to
-``sys.path`` so tests can import the ``widgets`` extension the same way
-``conf.py`` does in production.
+throw-away Sphinx project in a tmp dir. We also add the repo root to
+``sys.path`` so tests can import the docs extension via
+``docs._ext.widgets``, matching ``conf.py`` in production.
 """
 
 from __future__ import annotations
@@ -17,9 +17,8 @@
 
 _REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
 _DOCS_DIR = _REPO_ROOT / "docs"
-_EXT_DIR = _DOCS_DIR / "_ext"
-if str(_EXT_DIR) not in sys.path:
-    sys.path.insert(0, str(_EXT_DIR))
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
 
 
 @pytest.fixture
@@ -44,8 +43,8 @@ def real_widget_srcdir(tmp_path: pathlib.Path, docs_dir: pathlib.Path) -> pathli
     (srcdir / "conf.py").write_text(
         f"""
 import sys
-sys.path.insert(0, {str(_EXT_DIR)!r})
-extensions = ["myst_parser", "widgets"]
+sys.path.insert(0, {str(_REPO_ROOT)!r})
+extensions = ["myst_parser", "docs._ext.widgets"]
 exclude_patterns = ["_build"]
 master_doc = "index"
 source_suffix = {{".md": "markdown"}}

tests/docs/test_widgets.py

@@ -9,10 +9,11 @@
 import typing as t
 
 import pytest
-from widgets import BaseWidget
-from widgets._base import make_highlight_filter
-from widgets._discovery import discover
-from widgets.mcp_install import (
+
+from docs._ext.widgets import BaseWidget
+from docs._ext.widgets._base import make_highlight_filter
+from docs._ext.widgets._discovery import discover
+from docs._ext.widgets.mcp_install import (
     CLIENTS,
     METHODS,
     MCPInstallWidget,
@@ -73,7 +74,7 @@ def test_body_for_json_client_returns_config_snippet() -> None:
 
 def test_body_for_unknown_kind_raises() -> None:
     """An unrecognised ``client.kind`` surfaces as a ``ValueError``."""
-    from widgets.mcp_install import Client
+    from docs._ext.widgets.mcp_install import Client
 
     fake = Client(id="x", label="X", kind="bogus", config_file="")
     with pytest.raises(ValueError, match="unknown client kind"):