(tools:development)=
# 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 {ref}`Software used by QuantEcon <tools/software>`;
- the CI/CD workflows themselves — see {ref}`GitHub Actions Workflows <tools/github-actions>`.

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 {ref}`quantecon/actions <tools:github-actions: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](https://playwright.dev) (`@playwright/test`) | `quantecon-book-theme`, `quantecon-theme-src` | Visual-regression testing of the themes — screenshot a fixture site and diff against committed baselines. See {ref}`Visual regression testing <tools:playwright>`. |
| [pytest](https://docs.pytest.org) (`pytest-cov`, `pytest-regressions`) | `quantecon-book-theme`, `QuantEcon.py` | Python unit / build-output regression tests |
| [tox](https://tox.wiki) | `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](https://pre-commit.com) | `quantecon-book-theme` | Orchestrates the hooks below on each commit (`pre-commit install`); also run as a CI gate |
| [black](https://black.readthedocs.io) | `quantecon-book-theme` | Python code formatter |
| [flake8](https://flake8.pycqa.org) | `quantecon-book-theme`, `QuantEcon.py` | Python linter |
| [Prettier](https://prettier.io) | `quantecon-theme-src` | Formats `*.ts`, `*.tsx`, `*.md` (`npm run format`) |
| [ESLint](https://eslint.org) | `quantecon-theme-src` | TypeScript / React linting (`@remix-run/eslint-config`) |
| [TypeScript](https://www.typescriptlang.org) (`tsc`) | `quantecon-theme-src` | Type-checking, run in CI as `npm run compile` |

## Build & bundling

| Tool | Used in | Purpose |
|---|---|---|
| [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io) (`stb`) | `quantecon-book-theme` | Compiles the Sphinx theme and its web assets |
| [webpack](https://webpack.js.org) + npm | `quantecon-book-theme` | Bundles the theme's JS / SCSS (`npm run build`) |
| [Remix](https://remix.run) + [Tailwind CSS](https://tailwindcss.com) + npm | `quantecon-theme-src` | Builds the runtime MyST theme (`npm run prod:build`) |

## CI & coverage

| Tool | Used in | Purpose |
|---|---|---|
| [GitHub Actions](https://docs.github.com/actions) | All | Runs the tests, linters, and builds above. See {ref}`GitHub Actions Workflows <tools/github-actions>`. |
| [Codecov](https://about.codecov.io) | `quantecon-book-theme`, `QuantEcon.py` | Coverage reporting on pull requests |
| [Netlify](https://www.netlify.com) | `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
  {ref}`quantecon environment <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.
```