Contributing

Contributor-facing workflows: local environment setup, building the docs, and shell-script quality checks. Deeper build internals and the release runbook live on their own pages.

• Build infrastructure
• Update the package
• Appendix

Setup a Notebook Python environment

uv pip install -e '.[dev,docs,lab]'

Also install micromamba.

To use JupyterLab, you will need a ipykernel:

prefix=$(python -c "import sys; print(sys.prefix)")
jupyter kernelspec uninstall search_demo
python -m ipykernel install --prefix $prefix --name search_demo --display-name "search demo"

Build the docs

To build the Sphinx docs locally, you need to create the JupyterLite sites first (see Build infrastructure for what xeus.sh produces and the channel/CI constraints):

jupyterlite_build/xeus.sh

And then inject the docs:

sphinx-build -b html docs/ workspace/public/docs

The HTML output is written to workspace/public/docs/index.html.

To preview it locally:

python -m http.server 8000 --directory workspace/public

Then open http://localhost:8000/docs/.

Shell script checks

Use these commands from the repository root for shell script quality checks in scripts/*.sh.

Required tools:

• shfmt

• shellcheck

• bashate

Install on macOS:

brew install shfmt shellcheck
uv tool install bashate

Auto-fix formatting, then run linters:

shfmt -w jupyterlite_build/*.sh && shellcheck jupyterlite_build/*.sh && bashate -i E002,E003,E006 jupyterlite_build/*.sh

Check-only mode (no formatting changes):

shellcheck jupyterlite_build/*.sh && shfmt -d jupyterlite_build/*.sh && bashate -i E002,E003,E006 jupyterlite_build/*.sh