Skip to content

Template 0.1.32: the user docs link to the guide that owns a topic - #56

Merged
IvanHCenalmor merged 1 commit into
mainfrom
claude/funny-mclaren-9fdb98
Nov 16, 2026
Merged

IvanHCenalmor merged 1 commit into
mainfrom
claude/funny-mclaren-9fdb98

Conversation

@IvanHCenalmor

Copy link
Copy Markdown
Collaborator

Template 0.1.32: the template's user docs follow the one-owner rule agreed on 2026-11-16. Each topic is written on one page, and every other page links to it. The template owns "Install an app" (install.md) and the build guides. It does not own the plugins' install steps or how to write a tool.

What changed

.tools/docs/tools_bridge.md is rewritten around what the template owns:

  • Declare your tools: the <package>_lc_tools module under src/, a short example, keeping imports light, and naming the hosts in labconstrictor-app.yaml.
  • What the installer does: the order of post_install, pre_uninstall, and what happens when a step fails.
  • Which LabConstrictor Tools the installer installs: why it is pinned, where the pin is set (LC_TOOLS_PIN in both scripts, linked), LC_TOOLS_SPEC, and how maintainers move the pin.
  • If something does not work.

The page now links to the owner guides instead of repeating them:

The Tools pin's version (v0.3.0-alpha.2) is no longer written in any doc. The scripts are the only place it is set, and the page links to them. This also drops the maintainer step "update the tag in this paragraph".

.tools/docs/install.md: "Where the app is listed" writes napari in lower case and ends with one link to the image-software guide.
.tools/docs/README.md: the tools guide's entry writes napari in lower case.

Also checked, with nothing to change: the other user pages of .tools/docs and the template README. app_manifest.md names a plugin version only as an example value of host_requirements, which is the template's own field.

The plugin guides are owned by the plugin repositories (LabConstrictor-napari, LabConstrictor-Fiji and LabConstrictor-QuPath docs/user-guide.md; the overview and the authoring guide by LabConstrictor-Tools). The Site publishes them. This PR only links to them.

Delivered to apps: migration 0.1.31 → 0.1.32

  • .template_sync/migrations/v0_1_31_to_v0_1_32.py and its manifest.yaml entry (template_version: 0.1.32).
  • tools_bridge.md is replaced whole, but only when it is exactly the 0.1.31 template file (compared with LF endings). The frozen copies are in .template_sync/resources/v0_1_31_to_v0_1_32/ (new and previous/). A customised file is left alone with a SKIPPED line.
  • install.md and the docs README.md get exact-text edits. A file without that text gets a SKIPPED line, and a partly customised one gets the edits that apply.
  • The migration keeps each file's line endings, can run twice safely, and never creates or deletes a file.
  • Design note: .tools/docs/migration_0_1_32.md. It is not listed in the docs README.
  • Tests: tests/test_template_sync_0_1_32.py. tests/_v0_1_32.py (before_0_1_32) is chained into before_0_1_31, so the older frozen-resource tests still compare against the right text. Older exact-version assertions were already loosened. Three older tests read the live tools_bridge.md/install.md directly (test_template_sync_0_1_17.py, _0_1_28.py, _0_1_30.py). They now read the 0.1.31 text through before_0_1_32, so each still checks what it checked before. before_0_1_32 swaps the whole file back only when it is the 0.1.32 file, because before_0_1_20 runs the chain a second time on older text.

Verification

  • ruff 0.15.20: ruff check .template_sync .tools/python tests: all checks passed.
  • mypy 1.20.2: python -m mypy .template_sync .tools/python tests: no issues in 89 files.
  • pytest 9.1.1 (python -m pytest tests -q, CI's pins, Python 3.11, Windows), compared with a baseline on clean origin/main (87b4b97): 55 failed, 410 passed on this branch against 55 failed, 394 passed on clean main. The 55 failures are the same tests in both runs (they fail on clean main on Windows), so this change adds no failures. The 16 new tests pass.
  • Migration chain on copies of real apps (all at 0.1.31; sync.py --from-version 0.1.31 --to-version 0.1.32, then run again):
    App tools_bridge.md install.md docs README Second run
    NucleiSky replaced not present 1 edit no changes
    LabConstrictor-Playground replaced not present 1 edit no changes
    LabConstrictor-VLab4Mic replaced not present 1 edit no changes
    StarDist2D replaced 3 edits SKIPPED (the old main README, no tools entry) no changes
  • Links: every link in the changed pages resolves (external ones return HTTP 200; relative ones point to existing files).
  • Not run: the Site's own build against this branch.

Follow-ups (not in this PR)

  • When the Site publishes AUTHORING.md as a guide, a small migration should swap the GitHub address in tools_bridge.md for the Site one.
  • NucleiSky, Playground and VLab4Mic have no .tools/docs/install.md: no migration ever delivered it to them.

🤖 Generated with Claude Code

tools_bridge.md no longer repeats the plugins' install situation, the Tools
authoring guide (form markers, outputs, check/test) or the Tools pin's
version. It keeps what the template owns (where an app declares its tools,
what the installer does, where the pin is set and how it is moved) and links
to the owner guides: the Site's image-software, napari, Fiji and QuPath
guides, and LabConstrictor-Tools docs/AUTHORING.md (on GitHub for now).
install.md links to the image-software guide; napari in lower case.

Migration 0.1.31 -> 0.1.32 delivers it: tools_bridge.md is replaced only
when it is the 0.1.31 template file, install.md and the docs README get
exact-text edits, customised files are SKIPPED, line endings are kept.
Design note migration_0_1_32.md, tests, and before_0_1_32 chained into the
older test helpers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@IvanHCenalmor
IvanHCenalmor merged commit 9e7644c into main Nov 16, 2026
4 checks passed
@IvanHCenalmor
IvanHCenalmor deleted the claude/funny-mclaren-9fdb98 branch November 16, 2026 15:01
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