Development¶

Install precommit hooks for auto formatting.

PR without precommit formatting will not be accepted!

pre-commit install --install-hooks

Highly recommended to use jaxtyping to mark expected array shape, see good example of using jaxtyping

When using AI coding assistants, pls use desloppify to verify code quality before submitting PRs. Consider installing it as a pre-push git hook to catch issues early.

Run the tests¶

ruff check .
pytest tests
python scripts/docs.py build-all

Local Demonstration Workflow¶

Before relying on CI/CD, the entire docs pipeline can be verified locally in ~5 minutes.

1. Install docs dependencies¶

pip install -e .[docs]

or if you don't need to run ai auto generation,

pip install zensical>=0.0.32 mkdocstrings-python mkdocs-gen-files
pip install -e .

2. Serve English docs locally¶

python scripts/docs.py live en
# open http://127.0.0.1:8000

Note: zensical serve does not auto-reload on changes to source files outside the docs folder (e.g. btorch/). Refresh the browser manually when editing docstrings.

3. Run a single-page AI translation¶

export OPENAI_API_KEY=...
# Optional: use a different API provider (e.g. DeepSeek, Azure, local proxy)
export OPENAI_BASE_URL=https://api.deepseek.com
# Optional: use a different model (default is gpt-4o)
export OPENAI_MODEL=deepseek-chat
python scripts/translate.py translate-page \
  --language zh \
  --en-path docs/en/docs/installation.md
# inspect docs/zh/docs/installation.md

4. Serve Chinese docs locally¶

python scripts/docs.py live zh
# open http://127.0.0.1:8000/zh/

5. Build the full unified site¶

python scripts/docs.py build-all
# site/ now contains:
#   index.html          (English default)
#   zh/index.html       (Chinese)

6. Test incremental update (minimal-diff)¶

Edit one sentence in docs/en/docs/installation.md
Run python scripts/translate.py update-outdated --language zh
Verify git diff docs/zh/docs/installation.md only changes the corresponding sentence

7. Test manual-fix preservation¶

Add  around a paragraph in docs/zh/docs/installation.md
Edit the matching English source
Re-run update-outdated
Verify the frozen paragraph stays intact