contributing

thank you for considering contributing to importnb.

building

importnb can be built with a PEP 517 front end, such as build:

pyproject-build .

grammar

a lark grammar gives importnb line numbers from json. rebuild the grammar with lark installed:

python build_parser.py

note that a key section of the generated code is not reproducible, so the hash of the grammar file gets injected as a header comment.

both the grammar (json.g) and generated grammar (_json_parser.py, mpl-2.0 license) are checked into the repository.

testing

in a folder with pyproject.toml and docs, such as a git checkout or unpacked source distribution:

pytest

project

importnb uses pixi to fix, lint, test, build, build a lite demo, build docs, acceptance test the demo, and check that it is ready to release.

see all of the tasks with:

pixi task list

run all of them with:

pixi run all

or really run all of them, including tests of the oldest supported environment and the firefox-based browser tests:

pixi run all-epochs

interactive

the dev environment, a superset of most other environments, is available with extras tools for interactive development.

pixi run dev-lab          # start jupyterlab
pixi run dev-nb           # start notebook
pixi run docs-serve       # serve mkdocs with live reload
pixi run docs-lite-serve  # serve the jupyterlite demo

to use another editor in the dev environment with an editable install of importnb:

pixi run dev-pip
pixi run --environment dev path-to-your-editor .

continuous integration

importnb uses:

• GitHub Actions, defined in .github/workflows
• ReadTheDocs, defined in .readthedocs.yml