Contributing to tephpy#

Estimated reading time: 3 minutes

tephpy develops with pixi, which reads its environments from pyproject.toml and needs no setup of its own:

$ git clone git@github.com:bjlittle/tephpy.git
$ cd tephpy
$ pixi run tests

The first run builds the environment it needs. pixi run <task> selects that environment for you, so there is normally no --environment to remember.

What to Run#

Three commands are what a pull request must pass:

$ pixi run tests
$ pixi run lint
$ pixi run docs

pixi run docs builds the documentation and runs every gate over the result except one. It is the one to reach for. pixi run docs-all adds the gate it leaves out — a smoke test of the browser demo in Chromium.

The Task Graph#

Eighteen tasks are declared; about nine are worth knowing. The rest are steps these run on your behalf:

docs-clean ─→ docs-html ─→ docs-check-api        ─┐
                        ─→ docs-check-citations   │
                        ─→ docs-check-figures     ├─→ docs ─┐
                        ─→ docs-check-links       │         ├─→ docs-all
                        ─→ docs-check-tooltips   ─┘         │
                        ─→ docs-browser-test ───────────────┘

Task	What it does
`tests`	The suite, with image comparison enforced (Testing)
`tests-clean`	Removes what a test run leaves behind
`baselines`	Regenerates the pytest-mpl baselines
`lint`	Every pre-commit hook, over every file
`docs`	Builds the documentation and runs every gate over the result except the browser demo’s smoke test
`docs-all`	`docs`, plus the browser demo’s smoke test
`docs-figures`	Regenerates the published figures’ baselines
`serve-html`	Serves the built HTML locally
`manifest`	Checks `MANIFEST.in` against what the sdist carries

The Browser Demo Needs a Browser#

pixi run docs-all runs Playwright, which lives in the docs environment and is on no other PATH. Install a browser once:

$ pixi run -e docs playwright install chromium

On Linux the browser also needs system libraries pixi does not provide, which pixi run -e docs playwright install --with-deps chromium adds as root. Both go through pixi for the same reason. If the browser will not start, the check says which of the two is missing and names it the same way.

What a Pull Request Carries#

A changelog fragment — see Changelog Fragments.
A passing pixi run docs.
Prose reviewed against Reviewing Claims in Documentation Style.

Continuous Integration describes what runs once the pull request is open.