Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .template_sync/manifest.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
template_version: 0.1.34
template_version: 0.1.35
migrations:
- from: 0.0.0
to: 0.0.1
Expand Down Expand Up @@ -108,3 +108,6 @@ migrations:
- from: 0.1.33
to: 0.1.34
script: migrations/v0_1_33_to_v0_1_34.py
- from: 0.1.34
to: 0.1.35
script: migrations/v0_1_34_to_v0_1_35.py
200 changes: 200 additions & 0 deletions .template_sync/migrations/v0_1_34_to_v0_1_35.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
"""Template 0.1.34 -> 0.1.35: the user docs say how to uninstall an app, link to the website's guides, and use its heading style.

Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_35.md

The website (LabConstrictor-Site) publishes the template's .tools/docs as its guides. A review of the website on 2026-11-17 found errors in
them: a link to an uninstall guide that does not exist, links to a GitHub file where the website has the guide, a list of apps that drifts
from the App Centre, and headings that break the website's style. This migration brings the same fixes to an app repository.

What this changes in an app repository (every step is independent, idempotent and never deletes anything):

1. .tools/docs/use_cases.md is replaced by the 0.1.35 page, which links to the App Centre instead of keeping its own list of apps, when it is
still the 0.1.34 template file. A file the app changed itself stays as it is (SKIPPED).
2. .tools/docs/install.md gets an "Uninstall an app" section; the update steps link to it.
3. .tools/docs/troubleshooting_installed_app.md links to that section instead of download_executable.md.
4. .tools/docs/tools_bridge.md links to the website's "Writing tools" guide instead of the file on GitHub.
5. .tools/docs/notebook_usage.md names the applications menu on Linux (not the Start Menu).
6. .tools/docs/notebook_upload.md marks the version-check cell as Python.
7. Headings in sentence case, without emoji or trailing colons: code_hiding.md, before_getting_started.md, executable_creation.md,
workflow_status.md, installer_images.md.

Steps 2 to 7 replace exact pieces of template text and leave a passage alone when its text is not there (SKIPPED). The line endings of each
file are kept. The changes reach users with the app's next release.
"""
from __future__ import annotations

from pathlib import Path
from typing import Any


DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_35.md"
TAG = "[migration 0.1.35]"
RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_34_to_v0_1_35"
PREVIOUS_ROOT = RESOURCE_ROOT / "previous"

DOCS = Path(".tools/docs")
USE_CASES_DOC = DOCS / "use_cases.md"
INSTALL_DOC = DOCS / "install.md"
TROUBLESHOOTING_DOC = DOCS / "troubleshooting_installed_app.md"
TOOLS_DOC = DOCS / "tools_bridge.md"
USAGE_DOC = DOCS / "notebook_usage.md"
UPLOAD_DOC = DOCS / "notebook_upload.md"

SITE = "https://cellmigrationlab.github.io/LabConstrictor-Site/"
AUTHORING_ON_GITHUB = "https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md"
WRITING_TOOLS = f"{SITE}guides/writing-tools/"

UNINSTALL_SECTION = (
"## Uninstall an app\n"
"\n"
"Uninstalling deletes the app's install folder and everything in it: move anything you saved there to another folder first.\n"
"\n"
"- **Windows.** Open Settings > Apps > Installed apps, find the app, click the three dots next to it and choose Uninstall. You can also"
" double-click `Uninstall-<AppName>.exe` in the app's install folder. If the app is still listed afterwards, see"
" [Troubleshooting an installed app](troubleshooting_installed_app.md).\n"
"- **macOS and Linux.** Open a terminal and run the `uninstall.sh` script of the app's install folder (the folder you chose when you"
" installed it), for example `bash ~/labconstrictor/MyApp/uninstall.sh`. It removes the app's shortcut (from the Applications folder of"
" your home folder on macOS, from your applications menu on Linux), takes the app out of the tools list of napari, Fiji and QuPath, and"
" deletes the install folder.\n"
"\n"
)


def heading(old: str, new: str) -> tuple[str, str]:
"""A heading line, matched as a whole line."""
return (f"\n{old}\n", f"\n{new}\n")


# Files replaced whole, only when they are the 0.1.34 template file (compared with LF line endings).
WHOLE_FILES = (USE_CASES_DOC,)

# (old, new) pairs, written with LF line endings; a file with CRLF line endings gets them with CRLF.
EDITS: dict[Path, tuple[tuple[str, str], ...]] = {
INSTALL_DOC: (
("update an app by uninstalling the old version first and then installing the new one",
"update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one"),
("otherwise delete `<prefix>/pkgs` or uninstall the app and install it again.\n\n## Where the app is listed\n",
"otherwise delete `<prefix>/pkgs` or uninstall the app and install it again.\n\n" + UNINSTALL_SECTION + "## Where the app is listed\n"),
),
TROUBLESHOOTING_DOC: (
("as explained in the [uninstalling guide](./download_executable.md),",
"as explained in [Uninstall an app](install.md#uninstall-an-app),"),
),
TOOLS_DOC: (
(f"- [Writing tools]({AUTHORING_ON_GITHUB}), in LabConstrictor-Tools: the inputs\n",
f"- [Writing tools]({WRITING_TOOLS}): the inputs\n"),
(f"Test your tools before you publish a release, as [Writing tools]({AUTHORING_ON_GITHUB})\n",
f"Test your tools before you publish a release, as [Writing tools]({WRITING_TOOLS})\n"),
),
USAGE_DOC: (
("go to the Start Menu on Windows or Linux, or the Applications folder on macOS.",
"go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux)."),
),
UPLOAD_DOC: (
("so users can see there is a new version.\n\n```\n# @markdown Run this cell to check this notebook's version.\n",
"so users can see there is a new version.\n\n```python\n# @markdown Run this cell to check this notebook's version.\n"),
),
DOCS / "code_hiding.md": (
heading("## How is this for?", "## Who is this for?"),
),
DOCS / "before_getting_started.md": (
heading("## 🎯 LabConstrictor in a Nutshell", "## LabConstrictor in a nutshell"),
heading("### ⚙️ Easy Configuration", "### Easy configuration"),
heading("### 🖥️ Cross-Platform Installers", "### Cross-platform installers"),
heading("### 📦 Environment Management", "### Environment management"),
heading("### 📈 Version Control", "### Version control"),
heading("### ✨ User-Friendly Experience", "### User-friendly experience"),
heading("### 📱 Offline Usage", "### Offline usage"),
heading("## ✅ LabConstrictor Requirements", "## LabConstrictor requirements"),
),
DOCS / "executable_creation.md": (
heading("## ⚠️ Please check before proceeding:", "## Please check before proceeding"),
),
DOCS / "workflow_status.md": (
heading("## 1. Monitor the Progress", "## 1. Monitor the progress"),
heading("## 2. How to Debug a Failure", "## 2. How to debug a failure"),
heading("### 💡 Best Practice for Large Updates", "### Best practice for large updates"),
),
DOCS / "installer_images.md": (
heading("## Logo:", "## Logo"),
heading("## Banner:", "## Banner"),
heading("## Header:", "## Header"),
heading("## Default Installer", "## Default installer"),
heading("## Customised Installer", "## Customised installer"),
),
}
FILES = (*WHOLE_FILES, *EDITS)


def log(message: str) -> None:
print(f"{TAG} {message}")


def apply_edits(text_lf: str, edits: tuple[tuple[str, str], ...]) -> tuple[str, int, int]:
"""`text_lf` with each pair applied whose old text occurs exactly once and whose new text is not there yet. Returns the text, the
pairs applied and the pairs not found (neither the old text once nor the new text present)."""
applied = missing = 0
for old, new in edits:
if new in text_lf:
continue
if text_lf.count(old) == 1:
text_lf = text_lf.replace(old, new)
applied += 1
else:
missing += 1
return text_lf, applied, missing


def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]:
"""The 0.1.35 text of a whole-file step, and what was done. The text is unchanged when the file is not the 0.1.34 template file."""
new = (RESOURCE_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n")
if text_lf == new:
return text_lf, "already up to date"
previous = (PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n")
if text_lf != previous:
return text_lf, f"SKIPPED: customised (not the 0.1.34 template file), so it was left unchanged; compare it with the template's file. See {DOCS_URL}"
return new, "replaced by the 0.1.35 page"


def edited_file(relative: Path, text_lf: str) -> tuple[str, str]:
"""The text after the exact-text edits of `relative`, and what was done."""
edits = EDITS[relative]
text, applied, missing = apply_edits(text_lf, edits)
if not missing:
return text, f"{applied} text change(s)" if applied else "already up to date"
if missing == len(edits):
return text, f"SKIPPED: customised (the 0.1.34 text was not found), so it was left unchanged. See {DOCS_URL}"
skipped = f"SKIPPED {missing} passage(s) that differ from the template text (left as they are). See {DOCS_URL}"
return text, f"{applied} text change(s); {skipped}" if applied else f"the other changes are there; {skipped}"


def update(path: Path, relative: Path) -> str:
data = path.read_bytes().decode("utf-8")
newline = "\r\n" if "\r\n" in data else "\n"
original = data.replace("\r\n", "\n")
text, note = replaced_file(relative, original) if relative in WHOLE_FILES else edited_file(relative, original)
if text == original:
return note if note.startswith("SKIPPED") else f"unchanged: {note}"
path.write_bytes(text.replace("\n", newline).encode("utf-8"))
return f"updated: {note}"


def migrate(repo_root: Path, context: dict[str, Any]) -> None:
"""Apply the 0.1.35 documentation changes (idempotent, surgical, never raises for a customised file)."""
_ = context
changed = 0
for relative in FILES:
path = repo_root / relative
if not path.is_file():
log(f"{relative}: not present in this repository (nothing was created)")
continue
try:
status = update(path, relative)
except (OSError, UnicodeDecodeError) as exc:
status = f"SKIPPED: {exc}; left unchanged. See {DOCS_URL}"
changed += status.startswith("updated")
log(f"{relative}: {status}")
if changed:
log(f"done: {changed} file(s) changed. The changes reach users with the next release of the app.")
else:
log("done: no repository changes were required.")
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# LabConstrictor use cases

The apps already built with LabConstrictor are listed in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/). Each app's page says what the app does, links to its repository and offers its installers.

To list your own app there, see [Describe your app for the App Centre](app_manifest.md).
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# LabConstrictor use cases

Here are some tools that have already been created using LabConstrictor:
- [VLab4Mic](#vlab4mic)

## VLab4Mic

<p align="center">
<img src="https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor-VLab4Mic/main/app/logo/logo.png" alt="VLab4Mic Logo" width="80%">
</p>

[![Original GitHub Repo](https://img.shields.io/badge/GitHub-VLab4Mic-181717?logo=github)](https://github.com/HenriquesLab/VLab4Mic)
[![LabConstrictor GitHub Repo](https://img.shields.io/badge/GitHub-LabConstrictor--VLab4Mic-181717?logo=github)](https://github.com/CellMigrationLab/LabConstrictor-VLab4Mic)
[![bioRxiv Paper](https://img.shields.io/badge/bioRxiv-Paper-B31B1B)](https://www.biorxiv.org/content/10.64898/2026.06.02.729521v2)

**Abstract:**

Determining whether a microscopy experiment can resolve a specific feature of a protein assembly remains difficult because researchers must balance imaging modality, labelling strategy, and probe choice. We present VLab4Mic, a simulation platform that predicts structural resolvability before experiments. Starting from atomic models from the PDB or AlphaFold predictions, VLab4Mic places antibodies, nanobodies, chemical linkers, or fluorescent proteins on epitopes, applies stochastic labelling and steric constraints, and generates virtual samples for widefield, confocal, AiryScan, Stimulated Emission Depletion (STED), and Single-Molecule Localisation Microscopy (SMLM). Comparisons with nuclear pore complex data show realistic agreement across modalities. Case studies show that HIV capsid appearance depends strongly on orientation, and that STED and SMLM distinguish domed from flat clathrin lattices, whereas confocal and AiryScan struggle. VLab4Mic thereby helps researchers predict which biological questions are experimentally tractable with a given imaging configuration before spending time finetuning imaging parameters at the microscope.

A Bluesky post about VLab4Mic: [VLab4Mic on Bluesky](https://bsky.app/profile/henriqueslab.bsky.social/post/3mnw2p2j5pk24).
16 changes: 8 additions & 8 deletions .tools/docs/before_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,35 @@

Welcome to LabConstrictor! This guide will walk you through the basics and show you what you need to get started.

## 🎯 LabConstrictor in a Nutshell
## LabConstrictor in a nutshell

LabConstrictor is a template repository that lets you turn Jupyter notebooks into desktop apps. It handles the setup for you via automated GitHub Actions. Here are its main features:

### ⚙️ Easy Configuration
### Easy configuration

LabConstrictor has a web form that makes it easy to set up your repository, add your branding, and upload or update your notebooks and their dependencies.

### 🖥️ Cross-Platform Installers
### Cross-platform installers

Automatic workflows create installers for Windows (.exe), macOS (.pkg), and Linux (.sh). This makes it simple for users on any platform to install and run your notebooks. The installers are created using [Conda Constructor](https://github.com/conda/constructor).

### 📦 Environment Management
### Environment management

LabConstrictor uses `requirements.yaml` files to manage dependencies. Automatic workflows ensure your notebooks run consistently across different systems. LabConstrictor also includes helper notebooks for generating and validating requirement files.

### 📈 Version Control
### Version control

LabConstrictor includes helper cells that track notebook versions and notify users when updates are available. This way, everyone can use the latest features and fixes.

### ✨ User-Friendly Experience
### User-friendly experience

The installers take care of the setup, so users can open your notebooks with a desktop app. The app shows a Welcome Dashboard where users can check versions and pick notebooks. Notebooks have hidden code and a play button to run cells, giving a clean, app-like feel. Your repository can be private or public, giving you full control over who can access and use your notebooks.

### 📱 Offline Usage
### Offline usage

If your notebooks don’t need internet access, users can run the desktop apps offline after they install them.

## ✅ LabConstrictor Requirements
## LabConstrictor requirements

To get started with LabConstrictor, you only need the following:

Expand Down
2 changes: 1 addition & 1 deletion .tools/docs/code_hiding.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

LabConstrictor gives the option to hide code cells in Jupyter notebooks, making them cleaner and avoiding overwhelming users with too much code.

## How is this for?
## Who is this for?

This feature is only useful if your notebooks don't require any code modifications by the user. For example, if your notebook is purely for data visualisation and analysis, or if interaction with the user is done through widgets, hiding code cells can enhance the user experience. If your notebook requires users to modify code cells, it's best to keep them visible.

Expand Down
2 changes: 1 addition & 1 deletion .tools/docs/executable_creation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

After uploading your notebooks to the repository, follow these steps to create executable files for sharing.

## ⚠️ Please check before proceeding:
## Please check before proceeding

Open the Actions tab in your repository and check that no workflows are running. If one is in progress, wait until it finishes. Starting a release while other jobs are running may cause build conflicts.

Expand Down
9 changes: 8 additions & 1 deletion .tools/docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,16 @@ Installing takes about 6-8 minutes and you only do it once. You need an internet

## Update an installed app

- **macOS and Windows.** On macOS and Windows, update an app by uninstalling the old version first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again ([known issue](https://github.com/CellMigrationLab/LabConstrictor/issues/34)).
- **macOS and Windows.** On macOS and Windows, update an app by [uninstalling the old version](#uninstall-an-app) first and then installing the new one: the installer does not install over an existing install. On macOS, if you already ran the new installer over the old version and it stopped or reported a failure at the end, move only the old app shortcut (for example `~/Applications/MyApp.app`) to the Bin, keep the app's folder in your home folder, and run the installer again ([known issue](https://github.com/CellMigrationLab/LabConstrictor/issues/34)).
- **Linux.** On Linux, running the installer with `-u` updates in place only if the previous install finished; otherwise delete `<prefix>/pkgs` or uninstall the app and install it again.

## Uninstall an app

Uninstalling deletes the app's install folder and everything in it: move anything you saved there to another folder first.

- **Windows.** Open Settings > Apps > Installed apps, find the app, click the three dots next to it and choose Uninstall. You can also double-click `Uninstall-<AppName>.exe` in the app's install folder. If the app is still listed afterwards, see [Troubleshooting an installed app](troubleshooting_installed_app.md).
- **macOS and Linux.** Open a terminal and run the `uninstall.sh` script of the app's install folder (the folder you chose when you installed it), for example `bash ~/labconstrictor/MyApp/uninstall.sh`. It removes the app's shortcut (from the Applications folder of your home folder on macOS, from your applications menu on Linux), takes the app out of the tools list of napari, Fiji and QuPath, and deletes the install folder.

## Where the app is listed

If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools and passes the `hosts:` line of the app's `labconstrictor-app.yaml` (the installer bundles that file). A host lists the app only if the line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without the file, or without a `hosts:` line, the app is registered without hosts, every host lists it, and `menuinst_debug.log` in the install folder says so (`'<app>' declares no hosts, so it is listed in every host; ...`).
Expand Down
Loading
Loading