Skip to content

docs: migrate to Zensical and overhaul the documentation - #157

Open
tlambert03 wants to merge 30 commits into
mainfrom
docs-zensical
Open

tlambert03 wants to merge 30 commits into
mainfrom
docs-zensical

Conversation

@tlambert03

Copy link
Copy Markdown
Owner

This moves the docs from mkdocs-material to Zensical and rewrites most of the content.

  • Guide: pages on spaces, samples, channels, photometry, modalities, detectors, settings and saving. Each page describes what microsim computes at that stage, with the equations it uses.
  • Interactive charts: spectra, photon budget, fluorophore saturation, crosstalk between channels, detector SNR, EMCCD excess noise, PMT gain, HyD dead time, camera noise, and confocal pinhole size. They use Observable Plot and d3.
    • Where a chart recomputes physics in the browser, that code lives in docs/javascripts/physics/, and each function names the Python it mirrors.
    • tests/test_js_physics.py checks the JS against microsim in node.
    • Spectra and presets are exported from microsim at build time (including FPbase spectra), so the site makes no API calls when it runs.
  • Tutorials: plain Python and matplotlib. They are also built as notebooks, with "Open in Colab" and download buttons.
  • Figures: generated at build time by scripts/make_doc_figures.py and not committed. The exceptions are the logos and one COSEM example image, which needs to download data.
  • API reference: generated with api-autonav, one page per public module, with internal modules excluded. The overview page groups the main objects by topic.
  • Claude skills: two skills in .claude/skills/. check-js-physics checks the JS physics for drift from microsim, and check-docs-prose checks the written text against the code.
  • Source changes:
    • axis labels in OpticalConfig.plot_emission;
    • a module docstring for microsim.schema.
  • CI: the docs workflow generates the figures and notebooks, runs zensical build --strict, and deploys.

tlambert03 and others added 24 commits October 11, 2026 10:37
- replace mkdocs with Zensical (zensical.toml), mkdocstrings API reference
  with griffe-fieldz, mermaid, glightbox, abbreviations
- new structure: getting started, user guide, tutorials, API, about
- figures generated at build time by scripts/make_doc_figures.py
  (tutorial figures come from executing the tutorial page's code)
- version-pinning warnings on home, installation, settings, saving, README
- docstring fixes and additions across the schema
- move tutorial notebook to examples/notebooks
- CI builds with --strict and deploys via ghp-import

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed against microsim

- docs/javascripts/physics/photometry.js mirrors the photon budget calculations,
  with pointers to the Python; tests/test_js_physics.py runs it in node
- charts mount on Zensical's document$ (instant navigation), load Plot and d3
  from jsDelivr (pinned), and use CSS variables for light/dark
- spectra and filter data exported at build time to docs/data/generated/

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… HyD dead time)

- docs/javascripts/physics/detectors.js mirrors the detector formulas; the
  analytic SNR is tested against microsim's detector simulation
- SNR chart shows microsim Monte Carlo points at the starting parameters

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… notes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- scripts/make_notebooks.py converts each tutorial page to a notebook whose
  first cell installs microsim at the docs' commit; published with the site
- all tutorial figures are made by running the tutorial pages' code (the
  own-ground-truth and point-detector tutorials now include their plotting
  code); removes the hand-maintained tutorial notebook
- remove the unused light/dark matplotlib theming

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- noise: a microsim-simulated HeLa cell image recorded by a camera, with the
  noise drawn in the browser (simulateCamera, with seeded Poisson, gamma, and
  normal samplers); tested statistically against microsim's render
- pinhole: microsim PSFs across pinhole sizes, optical sectioning, and FWHM,
  all precomputed in Python

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- wording fixes across getting started, channels, samples, modalities
- correct what CosemLabel values mean; FPbase name matching; EGFP size
- API parameter tables fit the page; prose tables don't wrap names
- bleedthrough: interactive crosstalk matrix, and an EGFP/tdTomato example
  with bandpass vs longpass emission filters
- example output of the spectra plotting methods
- fix swapped axis labels in OpticalConfig.plot_emission
- confocal PSF equation; pinhole explorer can show the signal lost
- photon budget: drop specimen RI slider; saturation chart ranges

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…skill

- MatsLines parameter examples and an Allen neuron mask, made at build time
- three labels from two OpenOrganelle datasets, checked in (slow to make)
- document microsim.allen, and its current limits at optical resolution
- .claude/skills/check-docs-prose: auditing hand-written docs against code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nnels)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- one page per public module, from the source, replacing the hand-written
  API pages; modules re-exported by their package are excluded so each
  object is documented once
- cross-references to members point at their documented paths
- microsim.schema gets a module docstring for its (otherwise empty) page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…w by topic

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…arnings for pydantic models, use the canonical site URL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t clip at 0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…re to use

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…not a figure)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.33%. Comparing base (0aea364) to head (fb31816).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #157      +/-   ##
==========================================
+ Coverage   88.15%   88.33%   +0.18%     
==========================================
  Files          48       48              
  Lines        3292     3293       +1     
==========================================
+ Hits         2902     2909       +7     
+ Misses        390      384       -6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tlambert03 and others added 5 commits October 11, 2026 18:32
…t power, readout order, caches, run_batch, irradiance range)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…xported data

- halfSaturationIrradiance, maxEmissionRate, hydMaxRate, roundHalfEven, each
  tested against microsim
- photon budget chart uses photonBudget; test its result against
  Simulation.filtered_emission_rates
- noise, EMCCD, and PMT charts start from exported presets; photon budget and
  crosstalk use the exported ObjectiveLens defaults
- drop unused illumination/emission exports

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant