diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index 61747a8..aeb683c 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.34 +template_version: 0.1.35 migrations: - from: 0.0.0 to: 0.0.1 @@ -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 diff --git a/.template_sync/migrations/v0_1_34_to_v0_1_35.py b/.template_sync/migrations/v0_1_34_to_v0_1_35.py new file mode 100644 index 0000000..b374403 --- /dev/null +++ b/.template_sync/migrations/v0_1_34_to_v0_1_35.py @@ -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-.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 `/pkgs` or uninstall the app and install it again.\n\n## Where the app is listed\n", + "otherwise delete `/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.") diff --git a/.template_sync/resources/v0_1_34_to_v0_1_35/.tools/docs/use_cases.md b/.template_sync/resources/v0_1_34_to_v0_1_35/.tools/docs/use_cases.md new file mode 100644 index 0000000..9391efd --- /dev/null +++ b/.template_sync/resources/v0_1_34_to_v0_1_35/.tools/docs/use_cases.md @@ -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). diff --git a/.template_sync/resources/v0_1_34_to_v0_1_35/previous/.tools/docs/use_cases.md b/.template_sync/resources/v0_1_34_to_v0_1_35/previous/.tools/docs/use_cases.md new file mode 100644 index 0000000..9d3e328 --- /dev/null +++ b/.template_sync/resources/v0_1_34_to_v0_1_35/previous/.tools/docs/use_cases.md @@ -0,0 +1,20 @@ +# LabConstrictor use cases + +Here are some tools that have already been created using LabConstrictor: + - [VLab4Mic](#vlab4mic) + +## VLab4Mic + +

+ VLab4Mic Logo +

+ +[![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). diff --git a/.tools/docs/before_getting_started.md b/.tools/docs/before_getting_started.md index d47cd7a..033d911 100644 --- a/.tools/docs/before_getting_started.md +++ b/.tools/docs/before_getting_started.md @@ -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: diff --git a/.tools/docs/code_hiding.md b/.tools/docs/code_hiding.md index 31f013c..2e9cfce 100644 --- a/.tools/docs/code_hiding.md +++ b/.tools/docs/code_hiding.md @@ -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. diff --git a/.tools/docs/executable_creation.md b/.tools/docs/executable_creation.md index e104c40..008b322 100644 --- a/.tools/docs/executable_creation.md +++ b/.tools/docs/executable_creation.md @@ -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. diff --git a/.tools/docs/install.md b/.tools/docs/install.md index d324656..e4fcc0b 100644 --- a/.tools/docs/install.md +++ b/.tools/docs/install.md @@ -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 `/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-.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 (`'' declares no hosts, so it is listed in every host; ...`). diff --git a/.tools/docs/installer_images.md b/.tools/docs/installer_images.md index 1c3a589..e17f9c6 100644 --- a/.tools/docs/installer_images.md +++ b/.tools/docs/installer_images.md @@ -12,22 +12,22 @@ You can provide the following images for customisation: When preparing your images, please ensure they meet the recommended size and format for optimal display. Here are some examples of custom images used in an installer: -## Logo: +## Logo ![LabConstrictor Logo](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Logo.png) -## Banner: +## Banner ![LabConstrictor Banner](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Banner.png) -## Header: +## Header ![LabConstrictor Header](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/LabConstrictor_Header.png) -## Default Installer +## Default installer In case you do not provide any images during the initialisation of your repository, default placeholder images will be used: ![Default Installer Images](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Customisation_Default.png) -## Customised Installer +## Customised installer When you provide your own images, the installer will reflect your custom branding: diff --git a/.tools/docs/migration_0_1_35.md b/.tools/docs/migration_0_1_35.md new file mode 100644 index 0000000..33362c4 --- /dev/null +++ b/.tools/docs/migration_0_1_35.md @@ -0,0 +1,43 @@ +# Template 0.1.35: user docs fixed after a review of the website + +Design note for the 0.1.35 migration (`.template_sync/migrations/v0_1_34_to_v0_1_35.py`). How a change reaches an installed copy is described in [migration_0_1_16.md](migration_0_1_16.md): a new installer is needed, nothing edits an existing install. + +## 1. The problem + +The website ([LabConstrictor-Site](https://cellmigrationlab.github.io/LabConstrictor-Site/)) publishes the template's `.tools/docs` as its "Build an app" guides and a few user guides. A review of the website on 2026-11-17 found these errors in them: + +* `troubleshooting_installed_app.md` sent people to an "uninstalling guide" at `download_executable.md`, which is a stub until an app makes a release. No page said how to uninstall an app, while `install.md` tells macOS and Windows users to uninstall the old version before they update. +* `tools_bridge.md` linked "Writing tools" to `docs/AUTHORING.md` on GitHub; the website now publishes it as [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/), the page people read. +* `notebook_usage.md` said Linux has a Start Menu. +* `use_cases.md` listed one app while the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) lists every app built with LabConstrictor; a second list drifts. +* `notebook_upload.md` fenced its long Python cell without a language. +* Headings with emoji, Title Case or a trailing colon broke the website's heading style (sentence case, no emoji, no trailing colon); `code_hiding.md` asked "How is this for?". + +## 2. What changes + +| File | Change | +|---|---| +| `.tools/docs/install.md` | New section "Uninstall an app": on Windows, Settings > Apps > Installed apps or `Uninstall-.exe` in the install folder; on macOS and Linux, `bash /uninstall.sh`, which removes the app's shortcut, takes the app out of the tools list and deletes the install folder. The update steps link to it. | +| `.tools/docs/troubleshooting_installed_app.md` | Links to that section. | +| `.tools/docs/tools_bridge.md` | Both "Writing tools" links go to the website's guide. | +| `.tools/docs/notebook_usage.md` | Start Menu (Windows), Applications folder (macOS), applications menu (Linux), as the website's [/guides/using-apps/](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/using-apps/) says. | +| `.tools/docs/use_cases.md` | Links to the App Centre instead of keeping its own list. | +| `.tools/docs/notebook_upload.md` | The version-check cell is fenced as `python`. | +| `code_hiding.md`, `before_getting_started.md`, `executable_creation.md`, `workflow_status.md`, `installer_images.md` | Headings in sentence case, without emoji or trailing colons. No page of the template or of the website links to the old anchors. | + +The uninstall steps describe what the installer creates: `construct.yaml` ships `uninstall.sh` in the install folder on macOS and Linux, and `post_install.bat` lists the app under Installed apps with `Uninstall-.exe` as its uninstaller. + +## 3. What the migration does + +Every step is independent, idempotent, never deletes, never raises for a customised file (the sync pull request is still created) and keeps the line endings of each file. + +* **`use_cases.md`** is replaced by the 0.1.35 page when it is still the 0.1.34 template file (compared with LF line endings; the frozen copies are in `.template_sync/resources/v0_1_34_to_v0_1_35/`). An app that wrote its own page keeps it (`SKIPPED`). +* **The other pages**: each change replaces one exact piece of 0.1.34 text (a heading is matched as a whole line). A passage where that text is not found is left as it is (`SKIPPED`), and the other changes of the file are still made. + +## 4. Adopting it + +Take this template version (the synchronization pull request). Nothing else is needed: the docs change only. Users see the new pages on GitHub at once and in the app with its next release. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_35.py`): the resources are the live page and the 0.1.34 one; the live files are the 0.1.34 files migrated; the uninstall section names what the installer creates; no user page links to the download stub for uninstalling or to `AUTHORING.md` on GitHub; the headings of the changed pages have no emoji or trailing colon; the links and anchors of the changed pages resolve; the migration on 0.1.34 files with LF and CRLF line endings, on customised files, on a repository without the files, and a second run; the sync chain from 0.1.34. diff --git a/.tools/docs/notebook_upload.md b/.tools/docs/notebook_upload.md index 1341f14..3e00273 100644 --- a/.tools/docs/notebook_upload.md +++ b/.tools/docs/notebook_upload.md @@ -12,7 +12,7 @@ To ensure your notebook works with the versioning tracking provided by the LabCo > IMPORTANT NOTE: Each time you change the notebook's logic, update the version number on `current_version` variable so users can see there is a new version. -``` +```python # @markdown Run this cell to check this notebook's version. current_version = "0.0.1" diff --git a/.tools/docs/notebook_usage.md b/.tools/docs/notebook_usage.md index 2f86a28..10ff7a6 100644 --- a/.tools/docs/notebook_usage.md +++ b/.tools/docs/notebook_usage.md @@ -4,7 +4,7 @@ After you install the desktop application, this guide will show you how to use t ## 1. Launching the Application -To open the application, go to the Start Menu on Windows or Linux, or the Applications folder on macOS. Search for the application name and click its icon to start it. +To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. ## 2. Welcome Notebook diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index 9599e53..7ca94ae 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -6,7 +6,7 @@ function signatures. Nothing changes for apps that do not declare tools. This page covers what the template does: where you declare the tools and what the installer does with them. Two other guides cover the rest: -- [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md), in LabConstrictor-Tools: the inputs +- [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/): the inputs and outputs a tool can have, how to lay out its form, what each program supports, and how to test a tool. - [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/): what the people who install your app do to run its tools, with the install steps of the @@ -36,7 +36,7 @@ This page covers what the template does: where you declare the tools and what th Tools failed to install. An import at the top of your package does not stop the installation, because the installer installs Tools before it checks that your package can be imported. 3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`: see [Describe your app for the App Centre](app_manifest.md). -4. Test your tools before you publish a release, as [Writing tools](https://github.com/CellMigrationLab/LabConstrictor-Tools/blob/main/docs/AUTHORING.md) +4. Test your tools before you publish a release, as [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) shows (`labconstrictor-tools check` and `labconstrictor-tools test`). ## What the installer does diff --git a/.tools/docs/troubleshooting_installed_app.md b/.tools/docs/troubleshooting_installed_app.md index d186437..c91847b 100644 --- a/.tools/docs/troubleshooting_installed_app.md +++ b/.tools/docs/troubleshooting_installed_app.md @@ -4,7 +4,7 @@ Problems with an app on your computer, after you installed it. For problems with ## App still appears in the Windows Installed apps list after uninstalling -On Windows, it may happen that, after uninstalling the app from `Settings > Apps > Installed apps` as explained in the [uninstalling guide](./download_executable.md), the app still appears in the list and does not allow you to uninstall it again, showing a message like: +On Windows, it may happen that, after uninstalling the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app still appears in the list and does not allow you to uninstall it again, showing a message like: ![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) diff --git a/.tools/docs/use_cases.md b/.tools/docs/use_cases.md index 9d3e328..9391efd 100644 --- a/.tools/docs/use_cases.md +++ b/.tools/docs/use_cases.md @@ -1,20 +1,5 @@ # LabConstrictor use cases -Here are some tools that have already been created using LabConstrictor: - - [VLab4Mic](#vlab4mic) +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. -## VLab4Mic - -

- VLab4Mic Logo -

- -[![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). +To list your own app there, see [Describe your app for the App Centre](app_manifest.md). diff --git a/.tools/docs/workflow_status.md b/.tools/docs/workflow_status.md index 785917f..edd8476 100644 --- a/.tools/docs/workflow_status.md +++ b/.tools/docs/workflow_status.md @@ -2,7 +2,7 @@ When you upload a notebook or make a release, GitHub Actions starts a workflow to check your code and build the installers. The template synchronization workflow additionally requires the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md). -## 1. Monitor the Progress +## 1. Monitor the progress 1. Go to the **Actions** tab in your GitHub repository. 2. You’ll see a list of recent workflows. Find the one that matches your latest commit or release. @@ -10,7 +10,7 @@ When you upload a notebook or make a release, GitHub Actions starts a workflow t ![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) -## 2. How to Debug a Failure +## 2. How to debug a failure If the workflow fails, don’t worry. The system creates an error log that’s ready for you to use. @@ -26,7 +26,7 @@ If the workflow fails, don’t worry. The system creates an error log that’s r --- -### 💡 Best Practice for Large Updates +### Best practice for large updates If you’re planning a big update, like changing several notebooks or adding complex dependencies, don’t push straight to the main branch. diff --git a/tests/_v0_1_34.py b/tests/_v0_1_34.py index d27393f..08b96fe 100644 --- a/tests/_v0_1_34.py +++ b/tests/_v0_1_34.py @@ -8,6 +8,8 @@ from pathlib import Path +from _v0_1_35 import before_0_1_35 + PIN_0_1_33 = "v0.3.0-alpha.3" PIN_0_1_34 = "v0.3.0-alpha.4" PINNED_FILES = (Path("app/bash_bat_scripts/post_install.sh"), Path("app/bash_bat_scripts/post_install.bat")) @@ -15,6 +17,7 @@ def before_0_1_34(relative: Path | str, data: bytes) -> bytes: """`data` (a live template file at `relative`) with the 0.1.34 pin moved back; any other file is returned as it is.""" + data = before_0_1_35(relative, data) if Path(relative) not in PINNED_FILES: return data return data.replace(PIN_0_1_34.encode(), PIN_0_1_33.encode()) diff --git a/tests/_v0_1_35.py b/tests/_v0_1_35.py new file mode 100644 index 0000000..942d04f --- /dev/null +++ b/tests/_v0_1_35.py @@ -0,0 +1,44 @@ +"""Helper of the tests: a live template file as it was before template 0.1.35. + +Template 0.1.35 fixes user docs found wrong in a review of the website: an "Uninstall an app" section in install.md, links to the website's +guides, use_cases.md links to the App Centre, and headings in the website's style. The tests of the older migrations compare with the live +files; `before_0_1_35` gives the bytes of a live file without the 0.1.35 change (the frozen 0.1.34 copy for use_cases.md, the migration's +own edits undone for the others), so they keep checking what they checked. The 0.1.35 changes are tested in test_template_sync_0_1_35.py. +""" +from __future__ import annotations + +import importlib.util +from pathlib import Path +from types import ModuleType + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_34_to_v0_1_35.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_35_for_older_tests", MIGRATION_PATH) + if spec is None or spec.loader is None: + raise RuntimeError(f"Unable to load {MIGRATION_PATH}") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def before_0_1_35(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the change 0.1.35 made to it; any other file is returned as it is.""" + migration = _migration() + relative = Path(relative) + if relative not in migration.FILES: + return data + text = data.decode("utf-8") + newline = "\r\n" if "\r\n" in text else "\n" + if relative in migration.WHOLE_FILES: + # Only the 0.1.35 file is swapped back: older helpers may run this chain again on text that is already older. + if text.replace("\r\n", "\n") != (migration.RESOURCE_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n"): + return data + text = (migration.PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + else: + text = text.replace("\r\n", "\n") + for old, new in reversed(migration.EDITS[relative]): + text = text.replace(new, old, 1) + return text.replace("\n", newline).encode("utf-8") diff --git a/tests/test_template_sync_0_1_18.py b/tests/test_template_sync_0_1_18.py index 9b19abb..ab8df98 100644 --- a/tests/test_template_sync_0_1_18.py +++ b/tests/test_template_sync_0_1_18.py @@ -18,6 +18,7 @@ from _hosts import strip_hosts from _v0_1_20 import before_0_1_20 from _v0_1_28 import before_0_1_28 +from _v0_1_35 import before_0_1_35 ROOT = Path(__file__).resolve().parents[1] @@ -175,7 +176,8 @@ def test_the_tests_workflow_of_the_template(self) -> None: self.assertNotIn("LC_TOOLS_SPEC", text, "the smoke job installs the tag pinned by post_install: no Tools source override in CI") def test_the_install_rules_are_in_the_install_guide_with_one_wording(self) -> None: - guide = (ROOT / ".tools/docs/install.md").read_text(encoding="utf-8") + # 0.1.35 links "uninstalling the old version" to the uninstall section; the sentence is checked without that link. + guide = before_0_1_35(".tools/docs/install.md", (ROOT / ".tools/docs/install.md").read_bytes()).decode("utf-8") for rule in (RULE_PATH, RULE_UPDATE, RULE_LINUX): self.assertIn(rule, guide) markers = (("must contain no space", RULE_PATH), ("uninstalling the old version first", RULE_UPDATE), ("-u` updates in place", RULE_LINUX)) diff --git a/tests/test_template_sync_0_1_32.py b/tests/test_template_sync_0_1_32.py index 4b0f391..a90c4cd 100644 --- a/tests/test_template_sync_0_1_32.py +++ b/tests/test_template_sync_0_1_32.py @@ -15,6 +15,7 @@ from types import ModuleType from _v0_1_32 import before_0_1_32 +from _v0_1_33 import before_0_1_33 ROOT = Path(__file__).resolve().parents[1] @@ -40,6 +41,11 @@ def lf(path: Path) -> str: return path.read_bytes().decode("utf-8").replace("\r\n", "\n") +def live(relative: Path) -> bytes: + """The live template file as 0.1.32 left it (the later changes undone, tests/_v0_1_33.py and newer).""" + return before_0_1_33(relative, (ROOT / relative).read_bytes()) + + def old(relative: Path) -> bytes: """The 0.1.31 file: the live file without the 0.1.32 change.""" return before_0_1_32(relative, (ROOT / relative).read_bytes()) @@ -70,18 +76,18 @@ def test_the_design_note_exists_and_the_migration_links_it(self) -> None: def test_the_resources_are_the_live_guide_and_the_0_1_31_one(self) -> None: for relative in MIGRATION.WHOLE_FILES: with self.subTest(file=str(relative)): - self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), (ROOT / relative).read_bytes()) - self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), lf(ROOT / relative)) + self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), live(relative)) + self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), live(relative).decode("utf-8")) def test_the_live_files_are_the_0_1_31_files_migrated(self) -> None: for relative in MIGRATION.EDITS: with self.subTest(file=str(relative)): text, applied, missing = MIGRATION.apply_edits(old(relative).decode("utf-8"), MIGRATION.EDITS[relative]) self.assertEqual((applied, missing), (len(MIGRATION.EDITS[relative]), 0)) - self.assertEqual(text, lf(ROOT / relative)) + self.assertEqual(text, live(relative).decode("utf-8")) def test_the_tools_guide_links_the_owner_guides(self) -> None: - text = lf(ROOT / MIGRATION.TOOLS_DOC) + text = live(MIGRATION.TOOLS_DOC).decode("utf-8") for address in (f"{SITE}guides/image-software/", f"{SITE}guides/napari/", f"{SITE}guides/fiji/", f"{SITE}guides/qupath/", AUTHORING): with self.subTest(address=address): self.assertIn(f"]({address})", text) @@ -141,11 +147,11 @@ def run_migration(self) -> str: def test_an_app_of_0_1_31_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: for relative in MIGRATION.FILES: - self.assertNotEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes(), relative) + self.assertNotEqual((self.repo / relative).read_bytes(), live(relative), relative) log = self.run_migration() for relative in MIGRATION.FILES: with self.subTest(file=str(relative)): - self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertEqual((self.repo / relative).read_bytes(), live(relative)) self.assertIn(f"done: {len(MIGRATION.FILES)} file(s) changed", log) self.assertNotIn("SKIPPED", log) again = self.run_migration() @@ -160,7 +166,7 @@ def test_crlf_is_kept(self) -> None: with self.subTest(file=str(relative)): raw = (self.repo / relative).read_bytes() self.assertNotIn(b"\n", raw.replace(b"\r\n", b"")) - self.assertEqual(raw.replace(b"\r\n", b"\n"), (ROOT / relative).read_bytes()) + self.assertEqual(raw.replace(b"\r\n", b"\n"), live(relative)) def test_a_customised_guide_is_skipped(self) -> None: guide = self.put(MIGRATION.TOOLS_DOC, old(MIGRATION.TOOLS_DOC) + b"\nOur own note.\n") @@ -207,7 +213,7 @@ def test_the_sync_script_runs_the_migration_from_0_1_31(self) -> None: result = subprocess.run(command, capture_output=True, text=True, env=env, check=False) self.assertEqual(result.returncode, 0, result.stdout + result.stderr) self.assertIn("[migration 0.1.32]", result.stdout) - self.assertEqual((self.repo / MIGRATION.TOOLS_DOC).read_bytes(), (ROOT / MIGRATION.TOOLS_DOC).read_bytes()) + self.assertEqual((self.repo / MIGRATION.TOOLS_DOC).read_bytes(), live(MIGRATION.TOOLS_DOC)) again = subprocess.run(command, capture_output=True, text=True, env=env, check=False) self.assertIn("no repository changes were required", again.stdout) diff --git a/tests/test_template_sync_0_1_34.py b/tests/test_template_sync_0_1_34.py index 73e77db..54223ef 100644 --- a/tests/test_template_sync_0_1_34.py +++ b/tests/test_template_sync_0_1_34.py @@ -47,7 +47,7 @@ def test_the_template_pins_the_new_tag_once_per_script(self) -> None: def test_the_manifest_lists_the_migration_and_the_version(self) -> None: text = (ROOT / ".template_sync/manifest.yaml").read_text(encoding="utf-8") - self.assertIn("template_version: 0.1.34", text) # the newest migration: update when a later one is added + self.assertRegex(text, r"template_version: 0\.1\.(3[4-9]|[4-9][0-9])\b") self.assertIn("script: migrations/v0_1_33_to_v0_1_34.py", text) self.assertTrue((ROOT / ".tools/docs/migration_0_1_34.md").is_file()) diff --git a/tests/test_template_sync_0_1_35.py b/tests/test_template_sync_0_1_35.py new file mode 100644 index 0000000..8d9c496 --- /dev/null +++ b/tests/test_template_sync_0_1_35.py @@ -0,0 +1,238 @@ +"""Tests of the 0.1.35 migration: user docs fixed after a review of the website (uninstall steps, links to the website's guides, App Centre, +heading style).""" +from __future__ import annotations + +import importlib.util +import os +import re +import shutil +import subprocess +import sys +import tempfile +import unittest +from contextlib import redirect_stdout +from io import StringIO +from pathlib import Path +from types import ModuleType + +from _v0_1_35 import before_0_1_35 + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_34_to_v0_1_35.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" +SITE = "https://cellmigrationlab.github.io/LabConstrictor-Site/" + + +def load(path: Path, name: str) -> ModuleType: + spec = importlib.util.spec_from_file_location(name, path) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +MIGRATION = load(MIGRATION_PATH, "migration_0_1_35") + + +def lf(path: Path) -> str: + return path.read_bytes().decode("utf-8").replace("\r\n", "\n") + + +def old(relative: Path) -> bytes: + """The 0.1.34 file: the live file without the 0.1.35 change.""" + return before_0_1_35(relative, (ROOT / relative).read_bytes()) + + +def user_pages() -> list[Path]: + """The user-facing pages of .tools/docs (the migration_*.md design notes are history).""" + return sorted(path for path in DOCS.glob("*.md") if not path.name.startswith("migration_")) + + +def slug(title: str) -> str: + """The anchor GitHub and the website give a heading (lower case, punctuation dropped, spaces to hyphens).""" + return re.sub(r"[^\w\- ]", "", title.strip().lower()).replace(" ", "-") + + +class TemplateTests(unittest.TestCase): + def test_the_manifest_lists_the_migration_and_the_new_version(self) -> None: + text = lf(ROOT / ".template_sync/manifest.yaml") + self.assertRegex(text, r"template_version: 0\.1\.(3[5-9]|[4-9][0-9])\b") + self.assertIn("script: migrations/v0_1_34_to_v0_1_35.py", text) + + def test_chains_from_older_versions_reach_0_1_35(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_35") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.31", "0.1.34"): + self.assertEqual(sync.resolve_migration_chain(manifest["migrations"], start, "0.1.35")[-1]["to"], "0.1.35", start) + + def test_the_design_note_exists_and_the_migration_links_it(self) -> None: + self.assertTrue((DOCS / "migration_0_1_35.md").is_file()) + self.assertIn(".tools/docs/migration_0_1_35.md", MIGRATION.DOCS_URL) + self.assertNotIn("migration_0_1_35.md", lf(DOCS / "README.md"), "the docs README does not list design notes") + + def test_the_resources_are_the_live_page_and_the_0_1_34_one(self) -> None: + for relative in MIGRATION.WHOLE_FILES: + with self.subTest(file=str(relative)): + self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertNotEqual(lf(MIGRATION.PREVIOUS_ROOT / relative), lf(ROOT / relative)) + + def test_the_live_files_are_the_0_1_34_files_migrated(self) -> None: + for relative in MIGRATION.EDITS: + with self.subTest(file=str(relative)): + text, applied, missing = MIGRATION.apply_edits(old(relative).decode("utf-8"), MIGRATION.EDITS[relative]) + self.assertEqual((applied, missing), (len(MIGRATION.EDITS[relative]), 0)) + self.assertEqual(text, lf(ROOT / relative)) + + def test_install_says_how_to_uninstall_on_each_system(self) -> None: + text = lf(ROOT / MIGRATION.INSTALL_DOC) + self.assertEqual(text.count("\n## Uninstall an app\n"), 1) + section = text.split("\n## Uninstall an app\n", 1)[1].split("\n## ", 1)[0] + for needle in ("Settings > Apps > Installed apps", "`Uninstall-.exe`", "uninstall.sh", "macOS", "Linux"): + with self.subTest(text=needle): + self.assertIn(needle, section) + self.assertIn("[uninstalling the old version](#uninstall-an-app)", text) + + def test_the_names_in_the_uninstall_steps_are_those_the_installer_creates(self) -> None: + construct = lf(ROOT / "construct.yaml") + self.assertIn("app/bash_bat_scripts/uninstall.sh: uninstall.sh", construct, "uninstall.sh is shipped in the install folder") + bat = lf(ROOT / "app/bash_bat_scripts/post_install.bat") + self.assertIn('SET "UNINSTALL_EXE=%PREFIX%\\Uninstall-UNDERSCORED_PROJECT_NAME.exe"', bat) + self.assertIn("HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\", bat, "the app is in the Installed apps list") + + def test_no_user_page_links_to_the_download_stub_for_uninstalling_or_to_authoring_on_github(self) -> None: + for path in user_pages(): + text = lf(path) + with self.subTest(file=path.name): + self.assertNotIn("[uninstalling guide](./download_executable.md)", text) + self.assertNotIn(MIGRATION.AUTHORING_ON_GITHUB, text) + self.assertEqual(lf(ROOT / MIGRATION.TOOLS_DOC).count(f"]({MIGRATION.WRITING_TOOLS})"), 2) + self.assertIn("](install.md#uninstall-an-app)", lf(ROOT / MIGRATION.TROUBLESHOOTING_DOC)) + + def test_use_cases_links_to_the_app_centre(self) -> None: + text = lf(ROOT / MIGRATION.USE_CASES_DOC) + self.assertIn(f"]({SITE}apps/)", text) + self.assertNotIn("## VLab4Mic", text) + + def test_user_page_headings_follow_the_website_style(self) -> None: + emoji = re.compile("[☀-➿\U0001f300-\U0001faff]") + for relative in MIGRATION.EDITS: + for line in lf(ROOT / relative).splitlines(): + if not line.startswith("#"): + continue + with self.subTest(file=relative.name, heading=line): + self.assertIsNone(emoji.search(line)) + self.assertFalse(line.endswith(":")) + + def test_the_links_of_the_changed_pages_resolve(self) -> None: + for relative in MIGRATION.FILES: + for target, anchor in re.findall(r"\]\(([^)#\s]*)(?:#([^)\s]*))?\)", lf(ROOT / relative)): + if "://" in target: + continue + with self.subTest(file=str(relative), target=target, anchor=anchor): + page = ((ROOT / relative).parent / target).resolve() if target else ROOT / relative + self.assertTrue(page.exists()) + if anchor: + headings = [slug(line.lstrip("#")) for line in lf(page).splitlines() if line.startswith("#")] + self.assertIn(anchor, headings) + + +class MigrationTests(unittest.TestCase): + def setUp(self) -> None: + self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_35_")) + for relative in MIGRATION.FILES: + self.put(relative, old(relative)) + + def tearDown(self) -> None: + shutil.rmtree(self.repo, ignore_errors=True) + + def put(self, relative: Path, data: bytes) -> Path: + target = self.repo / relative + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(data) + return target + + def run_migration(self) -> str: + out = StringIO() + with redirect_stdout(out): + MIGRATION.migrate(self.repo, {}) + return out.getvalue() + + def test_an_app_of_0_1_34_gets_the_template_files_and_a_second_run_changes_nothing(self) -> None: + for relative in MIGRATION.FILES: + self.assertNotEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes(), relative) + log = self.run_migration() + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + self.assertIn(f"done: {len(MIGRATION.FILES)} file(s) changed", log) + self.assertNotIn("SKIPPED", log) + again = self.run_migration() + self.assertIn("no repository changes were required", again) + self.assertNotIn("SKIPPED", again) + + def test_crlf_is_kept(self) -> None: + for relative in MIGRATION.FILES: + self.put(relative, old(relative).replace(b"\n", b"\r\n")) + self.run_migration() + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + raw = (self.repo / relative).read_bytes() + self.assertNotIn(b"\n", raw.replace(b"\r\n", b"")) + self.assertEqual(raw.replace(b"\r\n", b"\n"), (ROOT / relative).read_bytes()) + + def test_a_customised_use_cases_page_is_skipped(self) -> None: + page = self.put(MIGRATION.USE_CASES_DOC, old(MIGRATION.USE_CASES_DOC) + b"\n## Our own app\n") + before = page.read_bytes() + log = self.run_migration() + self.assertIn(f"{MIGRATION.USE_CASES_DOC}: SKIPPED: customised (not the 0.1.34 template file)", log) + self.assertEqual(page.read_bytes(), before) + + def test_a_customised_passage_is_skipped_and_the_others_change(self) -> None: + relative = Path(".tools/docs/installer_images.md") + page = self.put(relative, b"# Our images\n\nOur own text.\n") + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised", log) + self.assertEqual(page.read_bytes(), b"# Our images\n\nOur own text.\n") + page.write_text(old(relative).decode("utf-8").replace("## Logo:\n", "## Our logo:\n"), encoding="utf-8", newline="\n") + log = self.run_migration() + self.assertIn(f"{relative}: updated: 4 text change(s); SKIPPED 1 passage(s)", log) + changed = lf(page) + self.assertIn("\n## Our logo:\n", changed) + self.assertIn("\n## Default installer\n", changed) + self.assertIn(f"{relative}: unchanged: the other changes are there; SKIPPED 1 passage(s)", self.run_migration()) + + def test_missing_files_are_not_created(self) -> None: + for relative in MIGRATION.FILES: + (self.repo / relative).unlink() + log = self.run_migration() + for relative in MIGRATION.FILES: + self.assertIn(f"{relative}: not present in this repository (nothing was created)", log) + self.assertEqual([p for p in self.repo.rglob("*") if p.is_file()], []) + + def test_a_file_that_is_not_text_is_skipped(self) -> None: + self.put(MIGRATION.INSTALL_DOC, b"\xff\xfe not utf-8") + log = self.run_migration() + self.assertIn(f"{MIGRATION.INSTALL_DOC}: SKIPPED", log) + self.assertEqual((self.repo / MIGRATION.INSTALL_DOC).read_bytes(), b"\xff\xfe not utf-8") + + def test_the_sync_script_runs_the_migration_from_0_1_34(self) -> None: + shutil.copytree(ROOT / ".template_sync", self.repo / ".template_sync") + # sync.py refuses a target other than the manifest version: pin the copy to 0.1.35 (later templates add migrations). + manifest = self.repo / ".template_sync/manifest.yaml" + manifest.write_text(re.sub(r"template_version: [0-9.]+", "template_version: 0.1.35", manifest.read_text(encoding="utf-8")), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", "0.1.34", "--to-version", "0.1.35", "--repository-root", str(self.repo)] + env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"} + result = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.35]", result.stdout) + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual((self.repo / relative).read_bytes(), (ROOT / relative).read_bytes()) + again = subprocess.run(command, capture_output=True, text=True, env=env, check=False) + self.assertIn("no repository changes were required", again.stdout) + + +if __name__ == "__main__": + unittest.main()