[tlambert03]

This is a work-in-progress proposal for a single, unified docs site for the whole ecosystem: pymmcore-plus, useq-schema, pymmcore-widgets, pymmcore-gui and napari-micromanager, built with zensical (the successor to mkdocs-material). I'm opening it early so people can browse it and weigh in. A preview link will show up in a comment below (it's rebuilt on every push).

The short version of what changes for readers:

• one site, with one navigation and one search across all packages (try searching setExposure or MDASequence)
• a new landing page and Getting Started section (which package do I need, install, three quickstarts, and a page for people coming from Micro-Manager)
• a User Guide organized by topic rather than by package (controlling hardware, describing experiments, running acquisitions, building GUIs, applications, ...)
• an API Reference for each package, generated from source, where every object is documented once, at its highest-level public name (pymmcore_plus.Device, not also pymmcore_plus.core.Device). other modules link to it under "Re-exports"
• the CMMCorePlus page is now a filterable explorer of all 342 methods (added / overridden / inherited / deprecated, by category), and finally includes the ~44 overload-only methods (setExposure, getXYPosition, ...) that were silently missing
• a widget gallery with screenshots generated from the examples
• all old URLs still work (/pymmcore-plus/..., /useq-schema/... etc. are preserved, and moved pages redirect)

And for maintainers:

• each package keeps its docs in its own docs/ folder (and docstrings), so a PR can still change code and docs together. member repos just have a small zensical.toml and .nav.yml files. this repo holds the theme, landing page, top-level navigation, and tools/compose.py, which assembles everything. zensical doesn't support composing multiple projects yet (it's on their roadmap), so the composer is meant as a stopgap that we can drop when that lands.
• pymmcore-plus is finally off the 2022 griffe fork: a ~25 line griffe extension handles pymmcore's stubs (I'll open issues upstream for the underlying bugs)
• member PRs will build the whole site with their changes; merges to main in any member trigger a deploy here
• the details are in the README and in Contributing > How these docs work in the preview

The member-side changes aren't PRs yet. They're on zensical-docs branches in my forks, and compose.overrides.toml points CI at them for now (it'll be deleted before merging):

• pymmcore-plus: diff
• useq-schema: diff
• pymmcore-widgets: diff
• pymmcore-gui: diff
• napari-micromanager: diff

One thing I want to be upfront about, since this was all done with Claude Code: most of the prose here was written by Claude, not me. The first version mostly carried over the existing docs. Since then there's been a full review pass: every page was read by fresh "readers" (newcomer, Micro-Manager expert, GUI user, structure, staleness, and voice), then rewritten where needed, with every code example run against the demo config. Comparing every page against the old docs on main now gives about 26k words of prose, of which about 63% is new, 13% is adapted from old text, and 25% is carried over verbatim.

So unless it's on the short list below, assume a page was largely written by Claude, and review it that way. The pages that are still mostly the old text are UniMMCore, event-driven acquisition, performance profiling, the useq-schema overview (about half), the axes schema page, and the metadata API page. Generated content (API pages, the CMMCorePlus table, widget pages) isn't counted, but docstrings were edited too: the src/ changes in all five repos are docstring-only (checked with an AST comparison against main).

New pages from the review pass: Coming from Micro-Manager, Using your own microscope, Saving data, Building sequences, and an Events reference. A few old example pages were folded into the guides (with redirects), and reference material moved out of the User Guide into the API Reference (constants, events, CLI, env vars). The review also turned up a handful of real bugs (e.g. mmcore run crashes, and a relative z plan without a stage position is centered on z = 0), which deserve their own issues rather than fixes in this PR.

Things I'd especially love feedback on:

1. does the overall organization make sense to you? (tabs, how the user guide is grouped, what's in Getting Started)
2. anything missing, broken, or confusing in the preview
3. the look & feel (landing page, colors, the CMMCorePlus explorer)

Not done yet (and not until there's some consensus): opening the member PRs, switching this repo's Pages deploy to Actions, retiring the old per-repo sites, and adding the token that lets members trigger deploys. (fwiw, this repo's Pages source is now the gh-pages branch, so previews can live under /pr-preview/... the root redirect there is unchanged.)

The preview workflow also builds on Windows, just to compare build times and widget screenshots (see the job summaries and the widget-screenshots-* artifacts).

🤖 Generated with Claude Code

https://claude.ai/code/session_019cDFrDDGJkJSy4zsEUj3Fp

[github-actions]

PR Preview Action v1.8.2
🚀 View preview at https://pymmcore-plus.github.io/pr-preview/pr-1/
Built to branch gh-pages at 2026-10-27 18:44 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[tlambert03]

hey @fdrgsp, @marktsuchida, @gselzer

here's a grand remake of the docs that claude whipped up in a drug-addled craze :)

https://pymmcore-plus.github.io/pr-preview/pr-1/

without feeling like you have to look at the code/structure... just look around the preview and let me know if you feel like it's a good direction. if you see anything wrong, or have any cool ideas, just make a quick qualitative note (without wasting too much time).

[marktsuchida]

Looks beautiful!

The only comment I had is that the full architecture diagram might be a bit intimidating as the first thing people see after clicking on Getting Started. Maybe the diagram could be moved to the end of that page (if not to the User Guide), starting the Which Package Do I Need? page with the Applications and Libraries?

[gselzer]

I'm also a big fan of this direction, and agree with @marktsuchida on the graph being scary 👿

Looking forward to seeing where it goes!

[tlambert03]

Thanks! Agree on the graph :)