sphinx-vite-builder 0.0.1a16.dev1__tar.gz → 0.0.1a16.dev2__tar.gz

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/AGENTS.md

@@ -29,6 +29,12 @@ asyncio loop in a daemon thread for sync↔async bridging),
 spawn install/build), and `errors.py` (`PnpmMissingError`,
 `NodeModulesInstallError`, `ViteFailedError`).
 
+**Phase 1 status:** The PEP 517 backend is fully implemented and
+tested. The Sphinx extension `setup()` is a placeholder — it
+registers cleanly in `conf.py` but doesn't yet hook the docs build
+lifecycle. The full extension implementation (event handlers, vite
+watch, teardown) lands in a follow-up release.
+
 ## The design contract — keep this invariant
 
 > **Sources should check for node, pnpm, etc and error if it's not
@@ -89,9 +95,9 @@ runs the wheel-from-sdist chain:
 Net: **sdist install also requires zero toolchain**. The
 `web/`-absent short-circuit is the load-bearing primitive.
 
-## The four QA permutations — keep them green
+## QA permutations — keep them green
 
-Verified end-to-end as of v0.0.1a16.dev0:
+The install-path permutations every change must keep green:
 
 | # | Path | Toolchain | Expected |
 |---|---|---|---|
@@ -152,7 +158,7 @@ resolution or distribution metadata, so wrapping them would be wrong.
 
 The workspace's `release.yml` MUST keep the pnpm + Node setup steps
 that run before `uv build`, otherwise the wheels published to PyPI
-would be empty of static (the v0.0.1a15 broken-release pattern that
+would be empty of static (the prior broken-release pattern that
 motivated this whole package). The required steps are:
 
 ```yaml

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-vite-builder
-Version: 0.0.1a16.dev1
+Version: 0.0.1a16.dev2
 Summary: PEP 517 build backend + Sphinx extension that orchestrates Vite via pnpm
 Project-URL: Repository, https://github.com/git-pull/gp-sphinx
 Author-email: Tony Narlock <tony@git-pull.com>
@@ -22,7 +22,6 @@ Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.10
-Requires-Dist: hatchling>=1.0
 Requires-Dist: sphinx>=8.1
 Description-Content-Type: text/markdown
 
@@ -70,8 +69,9 @@ backend at release time. The PEP 517 chain doesn't run on the
 consumer side. No backend invocation. No `pnpm`. No Node. The end
 user sees Python and only Python.
 
+No pnpm, no Node — just Python:
+
 ```console
-$ # No pnpm, no Node, no problem
 $ pip install gp-furo-theme
 ```
 
@@ -145,14 +145,16 @@ exclude = ["web/"]    # so the sdist→wheel chain hits the short-circuit
 artifacts = ["src/<your-theme>/theme/<theme-name>/static/"]
 ```
 
-### Sphinx extension
+### Sphinx extension (Phase 1: placeholder)
 
-Loaded from `conf.py`. Runs Vite as part of the docs lifecycle:
+The extension entry point is currently a placeholder registered in
+`conf.py` to prevent import errors. Full lifecycle integration —
+running Vite before the docs build and spawning a watched Vite
+process during `sphinx-autobuild` — lands in a follow-up release.
 
-- `sphinx-build` → `pnpm exec vite build` once before the docs build
-- `sphinx-autobuild` → `pnpm exec vite build --watch` as a child process
-  for the lifetime of the autobuild server, with idempotent re-fire on
-  rebuilds and graceful teardown on signal / `atexit`
+For now, the [PEP 517](https://peps.python.org/pep-0517/) backend
+handles all Vite orchestration during source builds and wheel
+generation; that path is fully implemented and tested.
 
 ```python
 # docs/conf.py

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/README.md

@@ -42,8 +42,9 @@ backend at release time. The PEP 517 chain doesn't run on the
 consumer side. No backend invocation. No `pnpm`. No Node. The end
 user sees Python and only Python.
 
+No pnpm, no Node — just Python:
+
 ```console
-$ # No pnpm, no Node, no problem
 $ pip install gp-furo-theme
 ```
 
@@ -117,14 +118,16 @@ exclude = ["web/"]    # so the sdist→wheel chain hits the short-circuit
 artifacts = ["src/<your-theme>/theme/<theme-name>/static/"]
 ```
 
-### Sphinx extension
+### Sphinx extension (Phase 1: placeholder)
 
-Loaded from `conf.py`. Runs Vite as part of the docs lifecycle:
+The extension entry point is currently a placeholder registered in
+`conf.py` to prevent import errors. Full lifecycle integration —
+running Vite before the docs build and spawning a watched Vite
+process during `sphinx-autobuild` — lands in a follow-up release.
 
-- `sphinx-build` → `pnpm exec vite build` once before the docs build
-- `sphinx-autobuild` → `pnpm exec vite build --watch` as a child process
-  for the lifetime of the autobuild server, with idempotent re-fire on
-  rebuilds and graceful teardown on signal / `atexit`
+For now, the [PEP 517](https://peps.python.org/pep-0517/) backend
+handles all Vite orchestration during source builds and wheel
+generation; that path is fully implemented and tested.
 
 ```python
 # docs/conf.py

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-vite-builder"
-version = "0.0.1a16.dev1"
+version = "0.0.1a16.dev2"
 description = "PEP 517 build backend + Sphinx extension that orchestrates Vite via pnpm"
 requires-python = ">=3.10,<4.0"
 authors = [
@@ -31,7 +31,6 @@ keywords = ["sphinx", "extension", "vite", "pnpm", "pep517", "build", "backend"]
 # required at build time of consumer packages but not at runtime, so it
 # stays in [build-system].requires of *consumers* rather than here.
 dependencies = [
-  "hatchling>=1.0",
   "sphinx>=8.1",
 ]
 

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/__init__.py

@@ -15,9 +15,13 @@ under :mod:`sphinx_vite_builder._internal`.
 
 from __future__ import annotations
 
+import logging
 import typing as t
 
-__version__ = "0.0.1a16.dev1"
+__version__ = "0.0.1a16.dev2"
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 if t.TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -31,6 +35,19 @@ def setup(app: Sphinx) -> dict[str, t.Any]:
     on ``sphinx-build``) lands in a follow-up commit. For now this
     stub registers the extension so consumers can declare it without
     a no-such-module error, and returns the safety metadata.
+
+    Examples
+    --------
+    The Phase-1 stub returns the parallel-safety metadata Sphinx
+    expects, regardless of the application object passed in:
+
+    >>> class FakeApp:
+    ...     pass
+    >>> metadata = setup(FakeApp())  # type: ignore[arg-type]
+    >>> metadata["parallel_read_safe"]
+    True
+    >>> metadata["parallel_write_safe"]
+    True
     """
     del app
     return {

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/_internal/process.py

@@ -9,9 +9,11 @@ backend and extension heads need:
 - ``PYTHONUNBUFFERED=1`` is forced into the child env so Python tools
   invoked via the package-manager bridge don't withhold their output.
 - On POSIX, the child runs in a new session (``start_new_session=True``)
-  so ``SIGTERM`` cleanly takes down the entire process tree (``pnpm exec``
-  shells out to multiple intermediate processes — without session
-  isolation, only the top-level pnpm wrapper would exit).
+  and :meth:`AsyncProcess.terminate` signals the whole process group
+  via :func:`os.killpg` so ``pnpm exec`` plus every descendant exits
+  together. ``asyncio.subprocess.Process.terminate`` would only signal
+  the leader's PID, leaving the vite child orphaned (pnpm does not
+  forward signals to its ``exec`` target).
 - :meth:`AsyncProcess.terminate` is graceful-then-forceful: SIGTERM,
   await up to ``timeout`` seconds, escalate to SIGKILL if the child is
   still alive. Idempotent: calling on an already-exited process is a
@@ -32,6 +34,7 @@ import contextlib
 import logging
 import os
 import pathlib
+import signal
 import sys
 import typing as t
 
@@ -196,7 +199,19 @@ class AsyncProcess:
         if self._process.returncode is not None:
             return self._process.returncode
 
-        self._process.terminate()
+        # POSIX: the child was spawned with ``start_new_session=True``,
+        # so ``self._process.pid`` is the leader of its own session and
+        # equals its process-group ID. SIGTERM the whole group so
+        # ``pnpm exec`` plus all its descendants (including the vite
+        # process pnpm doesn't forward signals to) exit. asyncio's
+        # ``Process.terminate()`` is PID-only — it would leave vite
+        # orphaned. Windows has no ``killpg``; the asyncio default is
+        # the right primitive there.
+        with contextlib.suppress(ProcessLookupError):
+            if sys.platform != "win32":
+                os.killpg(self._process.pid, signal.SIGTERM)
+            else:
+                self._process.terminate()
         try:
             await asyncio.wait_for(self._process.wait(), timeout=timeout)
         except asyncio.TimeoutError:
@@ -208,7 +223,10 @@ class AsyncProcess:
             # ProcessLookupError race: the child can exit between
             # TimeoutError and kill().
             with contextlib.suppress(ProcessLookupError):
-                self._process.kill()
+                if sys.platform != "win32":
+                    os.killpg(self._process.pid, signal.SIGKILL)
+                else:
+                    self._process.kill()
             await self._process.wait()
 
         # Wait for drainers to consume their last buffered line before

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/_internal/vite.py

@@ -1,13 +1,14 @@
-"""Vite + pnpm orchestration: detection, install, one-shot build, watch.
+"""Vite + pnpm orchestration: detection, install, one-shot build.
 
 This module is the shared orchestration core consumed by both heads:
 
 - The PEP 517 backend (:mod:`sphinx_vite_builder.build`) calls
   :func:`run_vite_build` from each of its hooks, before delegating to
   hatchling.
-- The Sphinx extension (:mod:`sphinx_vite_builder`) calls
-  :func:`run_vite_build` (one-shot) or its watch sibling from
-  ``builder-inited``.
+- The Sphinx extension (:mod:`sphinx_vite_builder`) — Phase 1
+  placeholder — will call :func:`run_vite_build` from
+  ``builder-inited`` once the extension head lands in a follow-up
+  release.
 
 Fast-fail discipline: every prerequisite is checked up front so the
 caller gets an actionable diagnostic instead of a generic spawn-failure
@@ -340,6 +341,22 @@ def run_vite_build(
       non-zero.
     - :class:`ViteFailedError` if ``pnpm exec vite build`` exits
       non-zero.
+
+    Examples
+    --------
+    The ``SPHINX_VITE_BUILDER_SKIP`` environment variable
+    short-circuits the whole orchestration before any subprocess is
+    spawned — exercising it from a doctest verifies the escape hatch
+    keeps working without touching pnpm, Node, or the filesystem
+    tree:
+
+    >>> import os, pathlib, tempfile
+    >>> os.environ["SPHINX_VITE_BUILDER_SKIP"] = "1"
+    >>> try:
+    ...     with tempfile.TemporaryDirectory() as tmp:
+    ...         run_vite_build(pathlib.Path(tmp))
+    ... finally:
+    ...     del os.environ["SPHINX_VITE_BUILDER_SKIP"]
     """
     if os.environ.get("SPHINX_VITE_BUILDER_SKIP"):
         logger.info("SPHINX_VITE_BUILDER_SKIP set; skipping vite build")

{sphinx_vite_builder-0.0.1a16.dev1 → sphinx_vite_builder-0.0.1a16.dev2}/src/sphinx_vite_builder/build.py

@@ -37,7 +37,41 @@ def build_wheel(
     config_settings: dict[str, t.Any] | None = None,
     metadata_directory: str | None = None,
 ) -> str:
-    """PEP 517 ``build_wheel``: vite-build, then hatchling-pack."""
+    """PEP 517 ``build_wheel``: vite-build, then hatchling-pack.
+
+    Examples
+    --------
+    With ``SPHINX_VITE_BUILDER_SKIP=1`` set, the hook short-circuits
+    vite and delegates straight to :mod:`hatchling.build` against a
+    minimal synthetic project, producing a real ``.whl``:
+
+    >>> import os, pathlib, tempfile, textwrap
+    >>> os.environ["SPHINX_VITE_BUILDER_SKIP"] = "1"
+    >>> cwd = os.getcwd()
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     project = pathlib.Path(tmp)
+    ...     _ = (project / "pyproject.toml").write_text(textwrap.dedent('''
+    ...         [build-system]
+    ...         requires = ["hatchling"]
+    ...         build-backend = "hatchling.build"
+    ...         [project]
+    ...         name = "doctest-pkg"
+    ...         version = "0.0.0"
+    ...     ''').lstrip())
+    ...     pkg = project / "doctest_pkg"
+    ...     pkg.mkdir()
+    ...     _ = (pkg / "__init__.py").write_text("")
+    ...     dist = project / "dist"
+    ...     dist.mkdir()
+    ...     os.chdir(project)
+    ...     try:
+    ...         name = build_wheel(str(dist))
+    ...     finally:
+    ...         os.chdir(cwd)
+    ...         del os.environ["SPHINX_VITE_BUILDER_SKIP"]
+    >>> name.endswith(".whl")
+    True
+    """
     run_vite_build()
     return _hatchling.build_wheel(wheel_directory, config_settings, metadata_directory)
 
@@ -47,7 +81,18 @@ def build_editable(
     config_settings: dict[str, t.Any] | None = None,
     metadata_directory: str | None = None,
 ) -> str:
-    """PEP 660 ``build_editable``: vite-build, then hatchling-pack-editable."""
+    """PEP 660 ``build_editable``: vite-build, then hatchling-pack-editable.
+
+    The delegation pattern matches :func:`build_wheel`; see that
+    function's docstring for an end-to-end example exercising the
+    ``SPHINX_VITE_BUILDER_SKIP=1`` short-circuit.
+
+    Examples
+    --------
+    >>> import inspect
+    >>> sorted(inspect.signature(build_editable).parameters)
+    ['config_settings', 'metadata_directory', 'wheel_directory']
+    """
     run_vite_build()
     return _hatchling.build_editable(
         wheel_directory, config_settings, metadata_directory
@@ -66,6 +111,16 @@ def build_sdist(
     the sdist without pnpm or Node — the wheel-from-sdist build will
     skip vite (no ``web/`` in the unpacked tree) and ship the
     pre-baked assets via hatchling's normal file selection.
+
+    The delegation pattern matches :func:`build_wheel`; see that
+    function's docstring for an end-to-end example exercising the
+    ``SPHINX_VITE_BUILDER_SKIP=1`` short-circuit.
+
+    Examples
+    --------
+    >>> import inspect
+    >>> sorted(inspect.signature(build_sdist).parameters)
+    ['config_settings', 'sdist_directory']
     """
     run_vite_build()
     return _hatchling.build_sdist(sdist_directory, config_settings)