API Reference

Config reference

Generated from add_config_value() registrations in sphinx_vite_builder/__init__.py.

sphinx_vite_builder_mode

config env

config env

sphinx_vite_builder_mode

Type:

str

Default:

'auto'

Registered by:

sphinx_vite_builder.setup()

sphinx_vite_builder_root

config env

config env

sphinx_vite_builder_root

Type:

None | str

Default:

None

Registered by:

sphinx_vite_builder.setup()

PEP 517 backend

sphinx_vite_builder.build.build_wheel(wheel_directory, config_settings=None, metadata_directory=None)

function

function

sphinx_vite_builder.build.build_wheel(wheel_directory, config_settings=None, metadata_directory=None)

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 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

Parameters:

• wheel_directory (str)

• config_settings (dict[str, Any] | None)

• metadata_directory (str | None)

Return type:

str

sphinx_vite_builder.build.build_editable(wheel_directory, config_settings=None, metadata_directory=None)

function

function

sphinx_vite_builder.build.build_editable(wheel_directory, config_settings=None, metadata_directory=None)

PEP 660 build_editable: vite-build, then hatchling-pack-editable.

The delegation pattern matches 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']

Parameters:

• wheel_directory (str)

• config_settings (dict[str, Any] | None)

• metadata_directory (str | None)

Return type:

str

sphinx_vite_builder.build.build_sdist(sdist_directory, config_settings=None)

function

function

sphinx_vite_builder.build.build_sdist(sdist_directory, config_settings=None)

PEP 517 build_sdist: pre-bake static so the sdist→wheel chain works.

Running vite at sdist-build time means the resulting .tar.gz contains a populated static/ tree (even though the source repo gitignores it). Downstream consumers can then pip install from 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 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']

Parameters:

• sdist_directory (str)

• config_settings (dict[str, Any] | None)

Return type:

str

Hatchling hook

class sphinx_vite_builder.hatch_plugin.ViteBuildHook

class

class

class sphinx_vite_builder.hatch_plugin.ViteBuildHook

Bases: BuildHookInterface[Any]

Run pnpm exec vite build before each hatchling build target.

Activated via [tool.hatch.build.hooks.vite] in a consumer’s pyproject.toml; the table key (vite) must match PLUGIN_NAME so hatchling can route the config block.

Examples

The class declares the canonical PLUGIN_NAME hatchling looks up when matching [tool.hatch.build.hooks.<name>] to a discovered hook. The name is part of the public contract — changing it would break existing consumer pyproject.toml configurations.

>>> ViteBuildHook.PLUGIN_NAME
'vite'

PLUGIN_NAME = 'vite'

attribute

attribute

PLUGIN_NAME = 'vite'

The name used for selection.

initialize(version, build_data)

method

method

initialize(version, build_data)

Run vite once before hatchling assembles version’s artefact.

Delegates to run_vite_build() so the SKIP env-var, web/-absent short-circuit, and fast-fail diagnostics behave identically to the PEP 517 backend variant.

Parameters:

• version (str)

• build_data (dict[str, Any])

Return type:

None

sphinx_vite_builder.hatch_plugin.hatch_register_build_hook()

function

function

sphinx_vite_builder.hatch_plugin.hatch_register_build_hook()

Hatchling plugin entry point.

Discovered via the [project.entry-points.hatch] vite = ... registration in this package’s pyproject.toml. Returns hook classes (not instances); hatchling instantiates them per build.

Examples

The function returns exactly one hook class so the [tool.hatch.build.hooks.vite] table key resolves to ViteBuildHook:

>>> hooks = hatch_register_build_hook()
>>> [hook.PLUGIN_NAME for hook in hooks]
['vite']

Return type:

list[type[BuildHookInterface[Any]]]

Diagnostic errors

class sphinx_vite_builder._internal.errors.SphinxViteBuilderError

class

class

class sphinx_vite_builder._internal.errors.SphinxViteBuilderError

Bases: Exception

Base class for all sphinx-vite-builder-raised diagnostic errors.

class sphinx_vite_builder._internal.errors.PnpmMissingError

class

class

class sphinx_vite_builder._internal.errors.PnpmMissingError

Bases: SphinxViteBuilderError

Raised when pnpm is not on PATH.

pnpm is not pip-installable, so the backend cannot bootstrap it the way maturin bootstraps Rust via puccinialin. The hint surfaces the canonical install paths (corepack enable, the pnpm.io install URL) so the user has an actionable next step.

class sphinx_vite_builder._internal.errors.NodeModulesInstallError

class

class

class sphinx_vite_builder._internal.errors.NodeModulesInstallError

Bases: SphinxViteBuilderError

Raised when pnpm install exits non-zero.

Surfaces the install command that failed and a re-run recipe. Callers should attach the captured stderr to the message before raising so the underlying pnpm diagnostic is visible at the call site.

class sphinx_vite_builder._internal.errors.ViteFailedError

class

class

class sphinx_vite_builder._internal.errors.ViteFailedError

Bases: SphinxViteBuilderError

Raised when pnpm exec vite build exits non-zero.

Surfaces the vite invocation that failed plus context (cwd, exit code). Callers should attach the captured stderr.