Development tooling

Development tooling#

This page tracks the software-development tooling used across QuantEcon’s actively-developed code repositories — the themes (quantecon-book-theme, quantecon-theme-src) and packages (QuantEcon.py). It is a living index: when we adopt, drop, or change a tool, update the table here so there is a single place to see what we test, lint, and build with.

Note

This page is about the tooling used to develop our code repositories. It is distinct from:

the build / publishing toolchain for lectures — see Software used by QuantEcon;
the CI/CD workflows themselves — see GitHub Actions Workflows.

QuantEcon’s lecture content repositories (e.g. lecture-python.myst, lecture-dp) carry almost none of the tooling below — their “test” is the Jupyter Book build itself, run with --warningiserror through the quantecon/actions library. The tools on this page apply to the repositories that ship code (Python / TypeScript), where unit tests, linters, and formatters matter.

Testing#

Tool	Used in	Purpose
Playwright (`@playwright/test`)	`quantecon-book-theme`, `quantecon-theme-src`	Visual-regression testing of the themes — screenshot a fixture site and diff against committed baselines. See Visual regression testing.
pytest (`pytest-cov`, `pytest-regressions`)	`quantecon-book-theme`, `QuantEcon.py`	Python unit / build-output regression tests
tox	`quantecon-book-theme`	Task runner and test-matrix driver (e.g. `py{312,313}` × `sphinx{7,8}`, and the `visual` / `visual-update` Playwright environments)

Linting & formatting#

Tool	Used in	Purpose
pre-commit	`quantecon-book-theme`	Orchestrates the hooks below on each commit (`pre-commit install`); also run as a CI gate
black	`quantecon-book-theme`	Python code formatter
flake8	`quantecon-book-theme`, `QuantEcon.py`	Python linter
Prettier	`quantecon-theme-src`	Formats `.ts`, `.tsx`, `*.md` (`npm run format`)
ESLint	`quantecon-theme-src`	TypeScript / React linting (`@remix-run/eslint-config`)
TypeScript (`tsc`)	`quantecon-theme-src`	Type-checking, run in CI as `npm run compile`

Build & bundling#

Tool	Used in	Purpose
sphinx-theme-builder (`stb`)	`quantecon-book-theme`	Compiles the Sphinx theme and its web assets
webpack + npm	`quantecon-book-theme`	Bundles the theme’s JS / SCSS (`npm run build`)
Remix + Tailwind CSS + npm	`quantecon-theme-src`	Builds the runtime MyST theme (`npm run prod:build`)

CI & coverage#

Tool	Used in	Purpose
GitHub Actions	All	Runs the tests, linters, and builds above. See GitHub Actions Workflows.
Codecov	`quantecon-book-theme`, `QuantEcon.py`	Coverage reporting on pull requests
Netlify	`quantecon-book-theme`	Deploys the fixtures site as a PR preview so reviewers can eyeball the theme

Version pinning#

Tool versions are pinned so local runs match CI:

Node — an .nvmrc in each theme repo pins the Node version (nvm use to match); CI reads the same file. quantecon-book-theme additionally pins node-version in pyproject.toml for sphinx-theme-builder.
Python — requires-python in pyproject.toml, with the supported matrix expressed in tox.ini / the CI workflow.
Build dependencies for lectures are pinned separately in the shared quantecon environment.

Tip

Keep this table in sync with reality. If you add a linter, swap a test runner, or retire a tool in one of the code repositories, edit the relevant section above in the same PR so the manual does not drift.