Development Workflow¶

This project includes a small Makefile and shell helpers for repeatable local development. The Makefile is the public entry point; the scripts underneath it are useful when a single command needs to be run directly.

Environment Setup¶

Create the local virtual environment and install development, documentation, and editable package dependencies:

make setup

make setup recreates venv/ and removes local build, tox, coverage, and packaging artifacts before installing dependencies. By default it uses python3. To choose another interpreter, set PYTHON_BIN:

PYTHON_BIN=python3.12 make setup

After setup, Makefile targets use tools from venv/bin instead of relying on globally installed commands.

The pytest configuration enforces 100% line and branch coverage for the lightbox package.

Make Targets¶

Run make or make help to print the available targets.

Target	Purpose
`make setup`	Recreate `venv/` and install development dependencies.
`make test`	Install the package in editable mode and run pytest.
`make lint`	Run `ruff check` and `ruff format --check`.
`make type`	Run `mypy lightbox`.
`make check`	Run lint, type checks, and tests.
`make html`	Refresh the PDF download if needed, build HTML docs, then validate the generated HTML.
`make pdf`	Build the LaTeX documentation and compile the PDF download.
`make docs`	Build PDF docs, build HTML docs, and validate the generated HTML.
`make validate`	Validate an existing `docs/_build/html` tree.
`make build`	Build source and wheel distributions, run `twine check`, and validate archive contents.
`make audit`	Run `pip-audit` against the local environment.
`make all`	Run checks, docs, package build, and dependency audit.
`make watch`	Start `sphinx-autobuild` for the documentation.
`make clean`	Remove generated build, cache, coverage, and packaging artifacts.
`make clean-all`	Clean generated artifacts, then run the full local gate.

Documentation Builds¶

The published GitHub Pages site includes a downloadable PDF, so the local docs targets keep the PDF and HTML output in sync. make html rebuilds the PDF first when docs/_downloads/sphinx-lightbox.pdf is missing or older than the documentation, Python, CSS, or JavaScript sources. That path requires a working LaTeX installation.

For HTML-only validation without LaTeX, use the same pattern as the CI docs check:

mkdir -p docs/_downloads
touch docs/_downloads/sphinx-lightbox.pdf
python -m sphinx -W --keep-going -E -a -b html docs docs/_build/html
python scripts/validate_docs.py docs/_build/html

tox -e docs also uses an HTML-only path with a placeholder PDF download.

Direct Script Usage¶

The Makefile delegates most commands to scripts/dev.sh. The direct form is useful in CI experiments or when invoking the workflow from another script:

./scripts/dev.sh check
./scripts/dev.sh docs
./scripts/dev.sh build

The script supports the same command names as the Makefile targets, without the make prefix.

Tox Matrix¶

Use tox when checking the supported Python and Sphinx combinations:

tox -p auto

The default matrix includes linting, type checking, documentation validation, and tests across Python 3.10 through 3.14 with supported Sphinx releases.

Release-Quality Local Gate¶

Before tagging a release, run the broad local gate when the system has the required tooling:

make all
tox -p auto

make all expects LaTeX for PDF generation and pip-audit for dependency auditing. The release checklist has the complete tagging and publishing steps.