Developer Notes#

Repository Rules#

  • Keep credentials, source PDFs, raw backups, notebook IDs, and local absolute paths out of Git.

  • Keep public paths project-relative.

  • Do not commit ref/, local_docs/, local_credentials/, backups/, build/, or dist/.

  • Production LabArchives code must stay read-only.

Useful Commands#

flutter test
flutter analyze
python3 scripts/labarchives_seed_bio_test_notebook.py --dry-run
python3 tool/build_quickstart_pdf.py
python3 docs_site/prepare_assets.py
sphinx-build -b html -W --keep-going docs_site/source docs_site/_build/html

When system Python lacks ReportLab or Sphinx, use an ignored local virtual environment or the bundled workspace Python available in Codex.

Documentation Site#

The Sphinx source lives under docs_site/source. The GitHub Pages workflow:

  1. installs docs_site/requirements.txt,

  2. copies tracked screenshots/PDF assets into _static,

  3. builds Sphinx with warnings as errors,

  4. uploads the HTML artifact,

  5. deploys it through GitHub Pages.

GitHub Pages is configured for workflow-based deployment, not branch-based Jekyll deployment.

References#