Skip to content

Template 0.1.37: corrected, clearer user docs, shipped to apps - #61

Merged
guijacquemet merged 12 commits into
mainfrom
claude/stardist-labconstrictor-plan-aizdd6
Nov 18, 2026
Merged

guijacquemet merged 12 commits into
mainfrom
claude/stardist-labconstrictor-plan-aizdd6

Conversation

@guijacquemet

Copy link
Copy Markdown
Collaborator

Part of the docs consolidation on the LabConstrictor website (Use / Build / Connect an app). A pass over the template's user docs for correctness, usefulness and readability, and a migration that brings the new pages to existing apps.

Pages

  • App users: notebook_usage.md (task sections: open the app, open / run / update a notebook, close, if something does not work), troubleshooting_installed_app.md (where the logs are; the certificate fix in plain words), install.md (adds "Check that it worked" and "If something does not work"; "Before you install" → "Before you start", the heading the site's check expects; per-system headings unchanged).
  • First-time builders: initialise_repository.md, notebook_requirements.md, notebook_upload.md, executable_creation.md get "What you need", "Check that it worked" and "If something does not work"; before_getting_started, create_repository, accept_pull_request, app_manifest, installer_images, troubleshooting, workflow_status, external_code_upload are shorter and plainer, without design-note links or version asides.
  • tools_bridge.md is now the entry page of the "Connect an app" track: the reader's four steps, then Writing tools; the maintainers' "Move the pin" paragraph is one sentence and a link.
  • template_synchronization.md: wrong Previous / Next links fixed; the three sections added.

Errors fixed

  • workflow_status: said to test big changes on a branch first; the update workflows only run on pushes to main/master.
  • notebook_upload: told readers to run a "bottom cell" that does not exist; the version lives only in current_version.
  • Now stated: the form accepts only package==version (requirements_format.py); all notebooks must share one python_version (merge_requirements.py:153); the generator's <notebook>_requirements.yaml is renamed by the form on upload; the form accepts only a classic ghp_ token.

Migration 0.1.36 → 0.1.37 (v0_1_36_to_v0_1_37.py, design note migration_0_1_37.md): replaces 17 guides whole, only when the app's copy is still the 0.1.36 file (LF comparison, app line endings kept); a changed copy is SKIPPED with a note; nothing is created or deleted. external_code_upload.md is recognised with the app's package name in place of PYTHON_PROJ_NAME. Older migrations' tests read live guides through tests/_v0_1_37.py (before_0_1_37); no frozen resource changed.

Tests: python -m unittest discover -s tests passes (500, 18 new in test_template_sync_0_1_37.py); mypy passes; ruff (CI version) passes. Not verified: the "Show/Hide Code" toolbar label.


Generated by Claude Code

…ges for app users

Lead with the task, one section per thing to do, add where the logs are, explain the
certificate workaround without implementation detail, and name the Welcome buttons
as the notebook shows them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…d and checks

Names the token the form accepts (classic, ghp_), the form's buttons and fields, the pull
request it opens, how to check the result and what to do when the form fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
The form accepts only package==version; all notebooks share one python_version; the
generator saves <notebook>_requirements.yaml. Updating a notebook no longer asks to run a
'bottom cell'. The upload page says what the workflow does and how to check it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…e and what to do on failure

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…ll_request

Plain, shorter text; numbered steps; each page points to the next step. accept_pull_request
says which LabConstrictor steps send pull requests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…ps design-note links

The PyPI section is left as it is (a migration resource must stay byte for byte equal).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…aintainers' site

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
The workflows run on pushes to main (and by hand), not on other branches, so the advice
to test a big update on a branch could not work: upload one notebook at a time instead.
The page also names the workflows and when the log artifact exists. installer_images:
plainer text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
… pass

install.md: 'Before you start', 'Check that it worked' and 'If something does not work'
(the site's checks for a critical guide); the system sections keep their headings.
tools_bridge.md opens with what the reader does, and links to the Tools operations page
instead of the maintainers' paragraph on moving the pin. template_synchronization.md:
footer links match its place in the docs index, plus a check step. The PyPI sections lose
their design-note links; app_manifest links the protocol page on the website.
Shipped to apps by the 0.1.37 migration (next commits).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
v0_1_36_to_v0_1_37.py replaces seventeen guides of .tools/docs whole, only when the app's
copy is still the 0.1.36 template file (LF comparison, the app's line endings kept,
SKIPPED otherwise, nothing created or deleted). external_code_upload.md is also recognised
with the app's package name in place of PYTHON_PROJ_NAME. Resources: the new pages and
previous/ (the 0.1.36 pages). Design note migration_0_1_37.md (not listed in the index).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
…0_1_37.py)

before_0_1_37 gives the frozen 0.1.36 copy of a guide that is the 0.1.37 page; it is
chained into before_0_1_36, and the 0.1.26, 0.1.35, 0.1.36 and token-integration tests
use it where they read a live guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
Resources are the live guides and differ from the frozen 0.1.36 copies; a 0.1.36 app
reaches the live guides (LF and CRLF kept) and a second run changes nothing; a customised
guide is SKIPPED; external_code_upload.md with the app's package name; missing files are
not created; a file that is not text is kept; sync.py from 0.1.36 and the chain from
0.1.35. Also checks the sections the website wants in the critical guides, the system
sections of install.md, the tools guide as an entry point and the sync guide's footer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WX6rdRdA72nsUjZvTXFSbP
@guijacquemet
guijacquemet merged commit d6e7f40 into main Nov 18, 2026
4 checks passed
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.

2 participants