Development Setup#

Set up a local development environment for quantecon-book-theme.

Prerequisites#

Python 3.12 or newer
Node.js 24 or newer — for compiling SCSS/JS assets with webpack
Git

Initial Setup#

Clone the repository:

git clone https://github.com/QuantEcon/quantecon-book-theme.git
cd quantecon-book-theme

Install Python tools (tox and pre-commit):
```
$ pip install tox pre-commit
```
Install Node.js dependencies:
```
$ npm install
```
Install pre-commit hooks:
```
$ pre-commit install
```
:::{margin} Run all pre-commit jobs manually:
```
$ pre-commit run --all-files
```
:::

Build the Documentation#

$ tox -e docs-update

This builds the docs and puts the output in docs/_build/html.

Auto-rebuild During Development#

$ tox -e docs-live

This starts a live-reload development server that watches for changes and automatically rebuilds. It will open in your default browser.

Run Tests#

$ tox

This runs pytest against Python 3.12 and 3.13. Pass arguments to pytest:

$ tox -- -k test_match

:::{tip} See Testing for detailed information about test fixtures and writing new tests. :::

Everything stays repo-local#

tox keeps the toolchain isolated to this repository — it builds its virtualenvs under .tox/ and installs the package plus its [test] extras there, never into your base/global Python. The theme’s SCSS/JS assets are compiled by sphinx-theme-builder, which provisions its own Node.js into an in-repo .nodeenv/; npm then installs into node_modules/ at the repository root. All three directories — .tox/, .nodeenv/, and node_modules/ — are git-ignored, so nothing leaks system-wide and the environment can always be rebuilt from scratch by deleting them.

Code Style#

Python#

Formatter: Black (88 char line length)
Linter: Flake8
Docstrings: Google style

JavaScript#

ES6+ (const/let, arrow functions, template literals)
JSDoc comments
100 char line length

SCSS#

Modern @use / @forward syntax (not @import)
BEM-inspired class naming
Maximum 3–4 levels of nesting

Troubleshooting#

`nodeenv-version-mismatch` when running `tox` or installing#

tox (or a pip install -e .) may fail with something like this:

× The `nodeenv` for this project is unhealthy.
╰─> There is a mismatch between what is present in the environment (v18.18.0)
    and the expected version of NodeJS (v20.18.0).

Your in-repo .nodeenv/ is stale — it was provisioned against an older pinned Node.js version and never refreshed. sphinx-theme-builder rebuilds it automatically once it’s removed:

$ rm -rf .nodeenv
$ tox

The pinned version lives under [tool.sphinx-theme-builder] (node-version) in pyproject.toml; deleting .nodeenv/ is always safe since it is git-ignored and regenerated on the next build.