Managed build environments

sphinxpress can create a dedicated virtual environment for Sphinx and project documentation dependencies. This is useful when the surrounding site pipeline is not a Python docs environment, such as a Jekyll-only GitHub Pages workflow.

Enable it with [build.env]:

[build.env]
enabled = true
scope = "shared"
python = "python3"
path = ".sphinxpress/venv"
upgrade_pip = true
packages = [
  "sphinx>=7",
  "myst-parser",
  "sphinx-rtd-theme",
  "weasyprint>=67",
  "tool-a==0.1.0",
]

When enabled, sphinxpress prepares the environment once per command and uses the venv-local sphinx-build executable for check, validate, build-site, build-epub, and build-pdf.

For PDF output, the same managed environment should also provide the weasyprint executable. Add weasyprint>=67 to [build.env].packages when you use the default WeasyPrint PDF backend.

Pip upgrade and install failures during managed environment setup are reported as a sphinxpress ValidationError and include the env-pip-upgrade or env-pip-install log path from [build].log_dir. The corresponding latest log file contains the full pip stdout, stderr, and return code.

Use exact package requirements for project packages, for example tool-a==0.1.0. Legacy editable entries that match a configured project path are converted to project-name==release-version using the project release tag with [release].tag_prefix stripped. Unmatched editable paths are rejected. Package path arguments after -r, --requirement, -c, and --constraint are resolved relative to sphinxpress.toml.

For v0.1, only scope = "shared" is supported. scope = "project" is reserved for a future release and is rejected with a configuration error.