diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index 153a7af..ae55fd3 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.39 +template_version: 0.1.40 migrations: - from: 0.0.0 to: 0.0.1 @@ -123,3 +123,6 @@ migrations: - from: 0.1.38 to: 0.1.39 script: migrations/v0_1_38_to_v0_1_39.py + - from: 0.1.39 + to: 0.1.40 + script: migrations/v0_1_39_to_v0_1_40.py diff --git a/.template_sync/migrations/v0_1_39_to_v0_1_40.py b/.template_sync/migrations/v0_1_39_to_v0_1_40.py new file mode 100644 index 0000000..5778ff7 --- /dev/null +++ b/.template_sync/migrations/v0_1_39_to_v0_1_40.py @@ -0,0 +1,134 @@ +"""Template 0.1.39 -> 0.1.40: an editorial pass on seven guides. + +Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_40.md + +Seven guides are rewritten to lead with what the reader does: filler, screenshot narration and brochure sections are removed, and the +behaviour they describe is unchanged. install.md no longer gives app users the `hosts:` rules of labconstrictor-app.yaml, and +workflow_status.md asks to remove tokens and private paths before showing a log to an AI assistant. + +What this changes in an app repository: each file in FILES is replaced by the 0.1.40 page when it is still the template file last shipped +(the 0.1.39 copy; compared with LF line endings; the file keeps its own line endings). A file the app changed itself stays as it is +(SKIPPED, with a note of what to change by hand). A missing file is not created, and nothing is deleted. external_code_upload.md is also +recognised with the app's Python package name in place of PYTHON_PROJ_NAME. The changes reach users with the app's next release. +""" +from __future__ import annotations + +import re +from pathlib import Path +from typing import Any + + +DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_40.md" +TAG = "[migration 0.1.40]" +RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_39_to_v0_1_40" +PREVIOUS_ROOT = RESOURCE_ROOT / "previous" + +DOCS = Path(".tools/docs") +EXTERNAL_CODE_DOC = DOCS / "external_code_upload.md" + +# Files replaced whole, only when they are the template file last shipped (the 0.1.39 copy, compared with LF line endings). +FILES = tuple( + DOCS / name + for name in ( + "before_getting_started.md", + "code_hiding.md", + "external_code_upload.md", + "install.md", + "notebook_portability.md", + "tools_bridge.md", + "workflow_status.md", + ) +) + +# What to change by hand in a customised file, by file (added to the SKIPPED note). +BY_HAND = { + DOCS / "before_getting_started.md": "nothing is required: the template's page condenses the six feature sections into two paragraphs", + DOCS / "code_hiding.md": "nothing is required: the template's page has a plainer first paragraph", + EXTERNAL_CODE_DOC: "nothing is required: the template's page has plainer instructions and calls \"Good to know\" \"Limits and options\"", + DOCS / "install.md": ( + "the section \"Where the app is listed\" of the template's page no longer explains the hosts: line of labconstrictor-app.yaml " + "(app users only need to know that the App Centre page says which programs an app works in)" + ), + DOCS / "notebook_portability.md": "nothing is required: the template's page has plainer instructions", + DOCS / "tools_bridge.md": "nothing is required: \"Apps that declare no tools are not affected\" moved to \"What the installer does\"", + DOCS / "workflow_status.md": ( + "if the page tells readers to paste the log file into an AI assistant, add that they must first remove tokens, private paths " + "and anything else they would not share, and check any suggested fix against the error before running the workflow again" + ), +} + +# The placeholder the repository form replaces in a guide, by guide: the form writes the app's Python package name in place of it. +RENDERED = {EXTERNAL_CODE_DOC: "PYTHON_PROJ_NAME"} +IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*" + + +def log(message: str) -> None: + print(f"{TAG} {message}") + + +def lf_text(path: Path) -> str: + return path.read_bytes().decode("utf-8").replace("\r\n", "\n") + + +def filled_in_name(template_lf: str, text_lf: str, placeholder: str) -> str | None: + """The name written in `text_lf` everywhere `template_lf` has `placeholder` (the same name each time), or None when the texts differ + elsewhere.""" + if placeholder not in template_lf: + return None + parts = template_lf.split(placeholder) + pattern = re.escape(parts[0]) + f"(?P{IDENTIFIER})" + "".join(re.escape(part) + "(?P=name)" for part in parts[1:-1]) + pattern += re.escape(parts[-1]) + match = re.fullmatch(pattern, text_lf, flags=re.DOTALL) + return match.group("name") if match else None + + +def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]: + """The 0.1.40 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.39 template file.""" + new = lf_text(RESOURCE_ROOT / relative) + previous = lf_text(PREVIOUS_ROOT / relative) + if text_lf == new: + return text_lf, "already up to date" + if text_lf == previous: + return new, "replaced by the 0.1.40 page" + placeholder = RENDERED.get(relative) + if placeholder: + name = filled_in_name(new, text_lf, placeholder) + if name: + return text_lf, "already up to date" + name = filled_in_name(previous, text_lf, placeholder) + if name: + return new.replace(placeholder, name), f"replaced by the 0.1.40 page (with the package name {name})" + by_hand = f" By hand: {BY_HAND[relative]}." if relative in BY_HAND else "" + return text_lf, f"SKIPPED: customised (not the 0.1.39 template file), so it was left unchanged; compare it with the template's page.{by_hand} See {DOCS_URL}" + + +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 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.40 documentation changes (idempotent, never raises for a customised file, creates and deletes nothing).""" + _ = 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_39_to_v0_1_40/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..22a82d5 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/before_getting_started.md @@ -0,0 +1,29 @@ +# Before getting started with LabConstrictor + +## LabConstrictor in a nutshell + +LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. A web form sets up your repository and uploads your notebooks with their requirements; GitHub Actions workflows in your repository do the rest. They merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app). + +The installed app opens JupyterLab with a Welcome notebook that lists your notebooks, shows when a newer version of one exists and updates it. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Once installed, the app runs without internet access, unless your notebooks need it. Your repository can be public or private; a private repository cannot be listed in the App Centre. + +## What you need + +- **A GitHub account**, to create your repository from the template. +- **Your Jupyter notebooks.** +- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand. +- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md). +- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md). + +Next: [Create your repository](create_repository.md). + + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](create_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/code_hiding.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/code_hiding.md new file mode 100644 index 0000000..3caf4dc --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/code_hiding.md @@ -0,0 +1,33 @@ +# Hide code cells in notebooks + +If people use your notebook through its widgets rather than by editing Python, you can hide the code and leave the controls visible. + +## 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. + +## How is this different from collapsing cells? + +JupyterLab already provides a way of collapsing the cell by clicking the blue bar on the left side of the cell. However, this method uncollapses the cell when the user clicks anywhere inside the cell, which can be inconvenient for users to chose the cell they want to run. + +This feature avoids that problem by providing a dedicated button to show or hide all code cells in the notebook and allowing the user to freely click the code cell. Additionally, when hiding code cells using this feature, a play button appears next to each code cell, allowing users to run code cells more intuitively. + +## How does the play button work? + +Depending on the versions of JupyterLab and ipywidgets you use, when code cells are hidden, a play button might show up next to each code cell: + +![Play Button vs Missing](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Cell_Button.png) + +Clicking this button runs the corresponding code cell without revealing the code. Whether or not the play button appears, you can always run a code cell by selecting it and clicking the play button in the top toolbar: + +![Toolbar Play Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Play_Button.png) + +## How to hide or show code cells? + +Depending on your initialisation your code cells will be hidden by default or shown by default. In either case, the visibility of code cells can be toggled using the `Show/Hide Code` button in the top toolbar: + +![Show Hide Code Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_ShowHide_Button.png) + +## Where is this controlled? + +Hiding code cells is done by a small script, [`hide_code_cells.py`](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/hide_code_cells.py). In your own repository it is `app/python_scripts/hide_code_cells.py`, and it runs when you upload or change a notebook. To switch the feature on or off, set `HIDE_CODE_DISABLED` in that file (`False` hides the code cells), or initialise your repository again with the [repository initialiser](https://labconstrictor-form.streamlit.app/) and choose the other option. diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..6dde54a --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/external_code_upload.md @@ -0,0 +1,124 @@ +# Upload external code + +Put your own Python code in your repository so that every notebook of your app can import it. + +## 1. Prepare your external code + +Put your functions in a package under `src/`: a folder with an `__init__.py` file, so notebooks can import it. List the packages your code needs in your notebooks' requirements. + +**Suggested folder structure:** + +```text +src/ +|-- PYTHON_PROJ_NAME/ +| |-- __init__.py +| |-- my_script.py +| |-- subpackage/ +| |-- __init__.py +``` + +### What goes in `__init__.py`? + +`__init__.py` tells Python that the folder is a package. It can stay empty. To let notebooks import your main functions directly from the package, re-export them: + +```python +# src/PYTHON_PROJ_NAME/__init__.py +from .my_script import run_analysis, load_config + +__all__ = ["run_analysis", "load_config"] +``` + +Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage. + +More on `__init__.py`: the [Real Python guide](https://realpython.com/python-init-py/). + +## 2. Upload your external code to the repository + +Open the `src` folder of your repository on GitHub and upload your files or folders there. + +![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif) + +## 3. How to import into your notebook + +Your notebooks import the code as a package: + +**Import the whole package:** +```python +import PYTHON_PROJ_NAME +``` + +If your folder under `src/` is called `celltools`, then `import celltools` will work because `src/celltools/__init__.py` exists. + +**Import function:** +```python +from PYTHON_PROJ_NAME import my_script +``` + +**Import submodule:** +```python +from PYTHON_PROJ_NAME.subpackage import submodule1 +``` + +## 4. Publish the code on PyPI (optional) + +The installer always puts your package into the app. You can also publish it on [PyPI](https://pypi.org), so that anyone can install it with `pip install`, in Google Colab or in their own Python. Each release then does both, with the same version: the GitHub Actions workflow `.github/workflows/publish_pypi.yml` builds the package and uploads it when you publish a release, next to the installers. + +It is **off until you turn it on**, and GitHub stores no password or token for it: PyPI trusts this repository's workflow directly ([trusted publishing](https://docs.pypi.org/trusted-publishers/)). + +**What is published** + +| | | +|---|---| +| Name | The `name=` of `setup.py`: the name of the package, given when the repository was initialised (unless you changed it). If `labconstrictor-app.yaml` has `distribution.pip`, it must be the same name. | +| Version | The release tag without the `v`: release `v1.2.0` publishes 1.2.0. | +| Code | Every package in `src/` (a folder with an `__init__.py`). | +| Dependencies | Each line of `requirements.txt`, as it is written (exact versions included). Options (`-r`, `--extra-index-url`), paths and URLs are left out, with a warning in the log: PyPI refuses dependencies given as URLs. | +| Description | `README.md` of the repository, shown on the PyPI page. | +| License | The `LICENSE` file. | + +### One-time setup + +1. **Check that the name is free.** Open `https://pypi.org/project//`. A "404 Not Found" page means nobody uses it. If it is taken, change `name=` in `setup.py` (and `distribution.pip`) and commit. +2. **Register this workflow on PyPI.** Log in to [pypi.org](https://pypi.org) (create an account if you have none; PyPI asks for two-factor authentication). Open your account menu > **Your projects** > **Publishing** ([pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)). Under **Add a new pending publisher**, choose the **GitHub** tab. The form has five fields; fill them in exactly: + - **PyPI Project Name:** the name of the package. + - **Owner:** the GitHub user or organisation that owns the repository (`CellMigrationLab` in `github.com/CellMigrationLab/MyApp`). + - **Repository name:** the repository (`MyApp`). + - **Workflow name:** `publish_pypi.yml` + - **Environment name:** `pypi` + + Click **Add**. The publisher appears under **Pending publishers** below the form. It does not reserve the name: the project is created by your first release. If the project already exists on PyPI and you own it, add the publisher in the project instead: **Your projects** > the project > **Manage** > **Publishing**. +3. **Turn it on in GitHub.** In the repository, open **Settings** > **Secrets and variables** > **Actions**, then the **Variables** tab (not **Secrets**: a secret cannot turn a workflow on). Click **New repository variable**, type `PYPI_PUBLISH` as the name and `true` as the value, and click **Add variable**. +4. **Publish a release** as usual ([Create executable installers](executable_creation.md)). In the **Actions** tab, the workflow **Publish the Python package to PyPI** runs next to **Build Release Installers**. When both jobs are green, the package is at `https://pypi.org/project//`. The upload job shows the link too. + +### Try it on TestPyPI first (optional) + +[TestPyPI](https://test.pypi.org) is a separate copy of PyPI for trials, with its own account. Add the same pending publisher at [test.pypi.org/manage/account/publishing](https://test.pypi.org/manage/account/publishing/), give the variable `PYPI_PUBLISH` the value `testpypi`, and publish a release. Install the result with: + +```bash +pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ +``` + +Then change the variable to `true`: the next release goes to PyPI. + +### Turn it off + +Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI. + +### Limits and options + +- **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. +- **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. +- **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**. +- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. +- If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails). + +--- + +
+ +[← Previous](app_manifest.md)            +[🏠 Home](README.md)            +[Next →](tools_bridge.md) + + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/install.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/install.md new file mode 100644 index 0000000..8312204 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/install.md @@ -0,0 +1,61 @@ +# Install an app + +Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release), then follow the steps for your system below. You install an app once; it can take several minutes. + +> **Check where it comes from.** The installers are not code-signed yet, so your system will warn you. Download only from the app's own GitHub release (the address starts with `https://github.com/` followed by the app's owner and repository, as shown on the app's page), and run it only if you trust that owner. A listing in the App Centre checks that the files come from the app's repository; it is not a security audit. + +## Before you start + +- **Internet connection.** The installer downloads the app's Python packages while it installs. +- **Install path.** The install path must contain no space: the installer refuses a path with a space. Use a path such as `C:\LabConstrictor\` on Windows or `~/labconstrictor/` on macOS and Linux. + +## Install on Windows + +1. Download the `.exe` file and double-click it. +2. If Windows shows "Windows protected your PC", click "More info" and then "Run anyway". The installers are not code-signed yet. + + ![Windows protected your PC: click More info, then Run anyway](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Protected_your_PC.png) + +3. Follow the on-screen prompts. A command prompt window opens during the installation: this is normal, do not close it. +4. Launch the app from the Start Menu or your desktop. + +## Install on a Mac + +1. Choose your file: open the Apple menu, then About This Mac. If the Chip or Processor says Intel, download the Intel installer; if it says M1, M2 or similar, download the Apple Silicon one. +2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway". The button appears only after you have tried to open the file once. +3. Follow the prompts (we recommend "Install only for me"). Launch the app from your Applications folder. + +## Install on Linux + +1. Download the `.sh` file. +2. Open a terminal in the download folder and run `bash` followed by the name of the file you downloaded, for example: `bash MyApp-0.1.0-Linux-x86_64.sh` +3. Follow the prompts, then launch the app from your applications menu. + +## Check that it worked + +Open the app. A terminal window opens, then JupyterLab opens in your web browser with the app's Welcome notebook. What to do next: [Open and use an app](notebook_usage.md). + +## If something does not work + +- The installer writes what it did to `menuinst_debug.log` in the install folder. +- See [Troubleshooting an installed app](troubleshooting_installed_app.md), or start from [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/). + +## Update an installed app + +- **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. +- **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 + +Some apps also work inside napari, Fiji or QuPath: the app's page in the App Centre says which. To use them there, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## Next + +Open the app and start working: [Open and use an app](notebook_usage.md). diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/notebook_portability.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/notebook_portability.md new file mode 100644 index 0000000..6cb4101 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/notebook_portability.md @@ -0,0 +1,131 @@ +# Write notebooks that run in both Google Colab and JupyterLab + +A LabConstrictor app runs your notebooks in JupyterLab on your colleagues' computers, while a reviewer may open the same notebook in Google Colab without installing anything. These practices keep one notebook working in both. + +## 1. Keep explanatory text visible when code is hidden + +LabConstrictor apps often hide code cells (see [Hide code cells in notebooks](code_hiding.md)). Put `# @title` on the first line of a cell: Colab shows it as the cell's header, and JupyterLab still shows it as the first line of the cell: + +```python +# @title Data input + +# Rest of the cell... +``` + +For an explanation longer than a line, use a Markdown cell: it stays visible everywhere, whether the code is hidden or not. + +## 2. Guard Colab-only setup code + +Run Colab-only setup (mounting Google Drive, installing GPU-only packages, `!pip` installs) only on Colab, so the notebook does not fail on a local computer: + +```python +import sys + +if 'google.colab' in sys.modules: + print("🚀 Detected Google Colab. Starting installation...") + + !pip install -q "cellpose[all]" tifffile + !pip install -q instanseg-torch + + from google.colab import userdata + from google.colab import drive + + drive.mount('/content/gdrive') + + print("✅ Colab setup done") +else: + # Fallback for local environments + print("⚠️ Not running in Colab. Please ensure dependencies are installed and data paths are set.") +``` + +## 3. Prefer cross-platform paths and storage + +- Use `pathlib.Path` and **relative paths** when possible. +- Avoid hard-coding Colab paths like `/content` or `/content/gdrive` outside guarded blocks. +- For data files, include a **config cell** where users can set a local path or select a file. + +## 4. Avoid Colab-only UI helpers + +Colab forms ([Google's guide](https://colab.research.google.com/notebooks/forms.ipynb)) do not work in JupyterLab. Use ipywidgets or simple input prompts instead: they work in both. + +For example, turn this Colab form: + +```python +model_name = "Model A" # @param ["Model A", "Model B", "Model C"] +print(f"You selected: {model_name}") +``` + +![Colab form example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/colab.png) + +into an ipywidgets dropdown: + +**Option A** - with an observable function: + +```python +import ipywidgets as widgets +from IPython.display import display + +model_dropdown = widgets.Dropdown( + options=["Model A", "Model B", "Model C"], + description="Select a model:", + style={'description_width': 'initial'} +) +output = widgets.HTML() + +def on_model_change(change): + if change['type'] == 'change' and change['name'] == 'value': + output.value = f"You selected: {change['new']}" +model_dropdown.observe(on_model_change) + +display(model_dropdown, output) +``` + +![ipywidgets dropdown example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/local_option1.png) + +**Option B** - With a button to confirm the selection: + +```python +import ipywidgets as widgets +from IPython.display import display + +model_dropdown = widgets.Dropdown( + options=["Model A", "Model B", "Model C"], + description="Select a model:", + style={'description_width': 'initial'} +) +confirm_button = widgets.Button(description="Confirm Selection") +output = widgets.HTML() + +def on_confirm_button_click(b): + output.value = f"You selected: {model_dropdown.value}" +confirm_button.on_click(on_confirm_button_click) + +display(model_dropdown, confirm_button, output) +``` + +![ipywidgets dropdown with button example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/local_option2.png) + +These examples need more code than a Colab form, but they work in both Colab and JupyterLab. + +## 5. Clearly label runtime-specific instructions + +When a step differs between the two, say so in a short Markdown note, for example: + +> **Colab users:** Run the `Colab setup` cell first to mount Google Drive. +> +> **JupyterLab users:** Skip the `Colab setup` cell and configure the local data path instead. + +## 6. Test in both environments before release + +Before you publish a notebook: + +1. Run it from start to end in **JupyterLab** (or local Jupyter), as the app will. +2. Run the same notebook in **Google Colab**. + +--- + +
+ +[🏠 Home](README.md) + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..c3c1db8 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/tools_bridge.md @@ -0,0 +1,78 @@ +# Expose your app's tools to napari, Fiji and QuPath + +Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. + +To expose your app's tools: + +1. Put your Python code in `src/` (see [Upload external code](external_code_upload.md)). +2. Declare the tools in a `_lc_tools` module, as shown below. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`. +4. Test the tools, then publish a release. + +How to write a tool, with its inputs, outputs, form layout and tests, is in [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/). What the people who install your app do to run the tools is in [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## What you need + +- An app repository made from this template, with your Python package in `src//`. +- Python functions with type annotations that you want to offer as tools. + +## Declare your tools + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. +2. If you can, import `labconstrictor_tools` only in `_lc_tools`, or inside functions. The rest of your package then also + works where LabConstrictor Tools is not installed: a notebook on Google Colab, a copy of the package used elsewhere, or an installation + where Tools failed to install. +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). + napari, Fiji and QuPath list your app only if `hosts:` names them. +4. Test your tools with `labconstrictor-tools check` and `labconstrictor-tools test`, as + [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) shows. + +## What the installer does + +When someone installs your app, the installer: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, it is unregistered. An app that declares no tools is not affected by any of this. + +If step 2 or 4 fails, the installer writes a `WARNING` to `menuinst_debug.log` in the install folder, skips the registration and finishes +the installation. The exception is a package that imports `labconstrictor_tools` at the top: then the import check of step 3 fails. + +The installer installs one fixed release of LabConstrictor Tools: the tag in `LC_TOOLS_PIN` of +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat). Template updates move it. To install Tools from +another source (a wheel, a git URL or a mirror), set the environment variable `LC_TOOLS_SPEC` when the installer runs; it replaces the pin. +How Tools releases are made and pinned is in +[Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/#pinning-tools-in-app-installers). + +## Check that it worked + +After you install a release of your app: + +- `menuinst_debug.log` in the install folder says `Tools registered`. +- `labconstrictor-tools list` shows your app and its tools. +- Your app appears in the programs you named under `hosts:`, once their plugin is installed. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. +- Other problems and their fixes: [Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/). diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/workflow_status.md b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/workflow_status.md new file mode 100644 index 0000000..6fe84cd --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/.tools/docs/workflow_status.md @@ -0,0 +1,36 @@ +# Check the status of GitHub workflows + +GitHub Actions runs workflows in your repository: when a notebook or its requirements change (**Updates on notebook change**), when the code in `src/` changes (**Updates on external code change**), when you publish a release (**Build Release Installers**) and every week for template updates (**Sync with Template Repository**, which needs the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md)). + +## 1. Monitor the progress + +1. Go to the **Actions** tab of your repository. +2. Find the run that matches your latest change or release. +3. Check its status icon: + +![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) + +## 2. How to debug a failure + +1. Click the failed run, then the red step: its log says what went wrong. + The log usually names the command or the package that failed. +2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed. +3. You can ask an AI assistant to help you read the log; the file starts with instructions for one. First remove tokens, private paths and anything else you would not share. Check any fix it suggests against the error, then run the workflow again. + +For known errors, see [Troubleshooting repository setup](troubleshooting.md). + +### Best practice for large updates + +The workflows run only on your main branch, so a change is checked once it is merged. For a big update, such as several notebooks or new dependencies, upload one notebook at a time and wait for the green tick before the next: a failure then points to one change. + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](troubleshooting.md) + + +
+ diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..16d81f9 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/before_getting_started.md @@ -0,0 +1,53 @@ +# Before getting started with LabConstrictor + +What LabConstrictor does, and what you need before you create your repository. + +## LabConstrictor in a nutshell + +LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building. + +### Easy configuration + +A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself. + +### Cross-platform installers + +Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app). + +### Environment management + +Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you. + +### Version control + +The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it. + +### User-friendly experience + +The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre. + +### Offline usage + +Once installed, the app runs without internet access, unless your notebooks need it. + +## LabConstrictor requirements + +- **A GitHub account**, to create your repository from the template. +- **Your Jupyter notebooks.** +- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand. +- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md). +- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md). + +Next: [Create your repository](create_repository.md). + + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](create_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/code_hiding.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/code_hiding.md new file mode 100644 index 0000000..2e9cfce --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/code_hiding.md @@ -0,0 +1,33 @@ +# Hide code cells in notebooks + +LabConstrictor gives the option to hide code cells in Jupyter notebooks, making them cleaner and avoiding overwhelming users with too much code. + +## 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. + +## How is this different from collapsing cells? + +JupyterLab already provides a way of collapsing the cell by clicking the blue bar on the left side of the cell. However, this method uncollapses the cell when the user clicks anywhere inside the cell, which can be inconvenient for users to chose the cell they want to run. + +This feature avoids that problem by providing a dedicated button to show or hide all code cells in the notebook and allowing the user to freely click the code cell. Additionally, when hiding code cells using this feature, a play button appears next to each code cell, allowing users to run code cells more intuitively. + +## How does the play button work? + +Depending on the versions of JupyterLab and ipywidgets you use, when code cells are hidden, a play button might show up next to each code cell: + +![Play Button vs Missing](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Cell_Button.png) + +Clicking this button runs the corresponding code cell without revealing the code. Whether or not the play button appears, you can always run a code cell by selecting it and clicking the play button in the top toolbar: + +![Toolbar Play Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Play_Button.png) + +## How to hide or show code cells? + +Depending on your initialisation your code cells will be hidden by default or shown by default. In either case, the visibility of code cells can be toggled using the `Show/Hide Code` button in the top toolbar: + +![Show Hide Code Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_ShowHide_Button.png) + +## Where is this controlled? + +Hiding code cells is done by a small script, [`hide_code_cells.py`](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/hide_code_cells.py). In your own repository it is `app/python_scripts/hide_code_cells.py`, and it runs when you upload or change a notebook. To switch the feature on or off, set `HIDE_CODE_DISABLED` in that file (`False` hides the code cells), or initialise your repository again with the [repository initialiser](https://labconstrictor-form.streamlit.app/) and choose the other option. diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..883a674 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/external_code_upload.md @@ -0,0 +1,125 @@ +# Upload external code + +If you want to use your own Python modules or scripts in Jupyter notebooks, follow these steps to upload them easily. + +## 1. Prepare your external code + +Organize your external code and follow Python packaging best practices. Set up the right folder structure, add an `__init__.py` file, and list any required dependencies. + +**Suggested Directory Structure:** + +```text +src/ +|-- PYTHON_PROJ_NAME/ +| |-- __init__.py +| |-- my_script.py +| |-- subpackage/ +| |-- __init__.py +``` + +### What goes in `__init__.py`? + +Think of `__init__.py` as the file that tells Python “this folder is a package”. + + If you leave it empty, that is perfectly fine—the package will still import correctly. When you want to make notebooks feel friendlier, you can re-export helper functions so users can discover them more easily: + +```python +# src/PYTHON_PROJ_NAME/__init__.py +from .my_script import run_analysis, load_config + +__all__ = ["run_analysis", "load_config"] +``` + +Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage. + +If you need further readings on `__init__.py`, check out this quick [Geeks for Geeks tutorial](https://www.geeksforgeeks.org/python/what-is-__init__-py-file-in-python/) or the [Real Python guide](https://realpython.com/python-init-py/). +## 2. Upload your external code to the repository + +Go to the src folder in your repository and upload your files or folders there. + +![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif) + +## 3. How to import into your notebook + +Once uploaded, your external code will be available to your notebooks as a package. To use it, import it as shown in the examples below: + +**Import the whole package:** +```python +import PYTHON_PROJ_NAME +``` + +If your folder under `src/` is called `celltools`, then `import celltools` will work because `src/celltools/__init__.py` exists. + +**Import function:** +```python +from PYTHON_PROJ_NAME import my_script +``` + +**Import submodule:** +```python +from PYTHON_PROJ_NAME.subpackage import submodule1 +``` + +## 4. Publish the code on PyPI (optional) + +The installer always puts your package into the app. You can also publish it on [PyPI](https://pypi.org), so that anyone can install it with `pip install`, in Google Colab or in their own Python. Each release then does both, with the same version: the GitHub Actions workflow `.github/workflows/publish_pypi.yml` builds the package and uploads it when you publish a release, next to the installers. + +It is **off until you turn it on**, and GitHub stores no password or token for it: PyPI trusts this repository's workflow directly ([trusted publishing](https://docs.pypi.org/trusted-publishers/)). + +**What is published** + +| | | +|---|---| +| Name | The `name=` of `setup.py`: the name of the package, given when the repository was initialised (unless you changed it). If `labconstrictor-app.yaml` has `distribution.pip`, it must be the same name. | +| Version | The release tag without the `v`: release `v1.2.0` publishes 1.2.0. | +| Code | Every package in `src/` (a folder with an `__init__.py`). | +| Dependencies | Each line of `requirements.txt`, as it is written (exact versions included). Options (`-r`, `--extra-index-url`), paths and URLs are left out, with a warning in the log: PyPI refuses dependencies given as URLs. | +| Description | `README.md` of the repository, shown on the PyPI page. | +| License | The `LICENSE` file. | + +### One-time setup + +1. **Check that the name is free.** Open `https://pypi.org/project//`. A "404 Not Found" page means nobody uses it. If it is taken, change `name=` in `setup.py` (and `distribution.pip`) and commit. +2. **Register this workflow on PyPI.** Log in to [pypi.org](https://pypi.org) (create an account if you have none; PyPI asks for two-factor authentication). Open your account menu > **Your projects** > **Publishing** ([pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)). Under **Add a new pending publisher**, choose the **GitHub** tab. The form has five fields; fill them in exactly: + - **PyPI Project Name:** the name of the package. + - **Owner:** the GitHub user or organisation that owns the repository (`CellMigrationLab` in `github.com/CellMigrationLab/MyApp`). + - **Repository name:** the repository (`MyApp`). + - **Workflow name:** `publish_pypi.yml` + - **Environment name:** `pypi` + + Click **Add**. The publisher appears under **Pending publishers** below the form. It does not reserve the name: the project is created by your first release. If the project already exists on PyPI and you own it, add the publisher in the project instead: **Your projects** > the project > **Manage** > **Publishing**. +3. **Turn it on in GitHub.** In the repository, open **Settings** > **Secrets and variables** > **Actions**, then the **Variables** tab (not **Secrets**: a secret cannot turn a workflow on). Click **New repository variable**, type `PYPI_PUBLISH` as the name and `true` as the value, and click **Add variable**. +4. **Publish a release** as usual ([Create executable installers](executable_creation.md)). In the **Actions** tab, the workflow **Publish the Python package to PyPI** runs next to **Build Release Installers**. When both jobs are green, the package is at `https://pypi.org/project//`. The upload job shows the link too. + +### Try it on TestPyPI first (optional) + +[TestPyPI](https://test.pypi.org) is a separate copy of PyPI for trials, with its own account. Add the same pending publisher at [test.pypi.org/manage/account/publishing](https://test.pypi.org/manage/account/publishing/), give the variable `PYPI_PUBLISH` the value `testpypi`, and publish a release. Install the result with: + +```bash +pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ +``` + +Then change the variable to `true`: the next release goes to PyPI. + +### Turn it off + +Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI. + +### Good to know + +- **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. +- **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. +- **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**. +- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice. +- If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails). + +--- + +
+ +[← Previous](app_manifest.md)            +[🏠 Home](README.md)            +[Next →](tools_bridge.md) + + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/install.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/install.md new file mode 100644 index 0000000..9bf667b --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/install.md @@ -0,0 +1,63 @@ +# Install an app + +Download the installer for your system from the app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) (or from the app's GitHub release), then follow the steps for your system below. You install an app once; it can take several minutes. + +> **Check where it comes from.** The installers are not code-signed yet, so your system will warn you. Download only from the app's own GitHub release (the address starts with `https://github.com/` followed by the app's owner and repository, as shown on the app's page), and run it only if you trust that owner. A listing in the App Centre checks that the files come from the app's repository; it is not a security audit. + +## Before you start + +- **Internet connection.** The installer downloads the app's Python packages while it installs. +- **Install path.** The install path must contain no space: the installer refuses a path with a space. Use a path such as `C:\LabConstrictor\` on Windows or `~/labconstrictor/` on macOS and Linux. + +## Install on Windows + +1. Download the `.exe` file and double-click it. +2. If Windows shows "Windows protected your PC", click "More info" and then "Run anyway". The installers are not code-signed yet. + + ![Windows protected your PC: click More info, then Run anyway](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Protected_your_PC.png) + +3. Follow the on-screen prompts. A command prompt window opens during the installation: this is normal, do not close it. +4. Launch the app from the Start Menu or your desktop. + +## Install on a Mac + +1. Choose your file: open the Apple menu, then About This Mac. If the Chip or Processor says Intel, download the Intel installer; if it says M1, M2 or similar, download the Apple Silicon one. +2. Double-click the `.pkg` file. If macOS refuses to open it, go to System Settings, Privacy & Security, scroll down to the message about the package and click "Open Anyway". The button appears only after you have tried to open the file once. +3. Follow the prompts (we recommend "Install only for me"). Launch the app from your Applications folder. + +## Install on Linux + +1. Download the `.sh` file. +2. Open a terminal in the download folder and run `bash` followed by the name of the file you downloaded, for example: `bash MyApp-0.1.0-Linux-x86_64.sh` +3. Follow the prompts, then launch the app from your applications menu. + +## Check that it worked + +Open the app. A terminal window opens, then JupyterLab opens in your web browser with the app's Welcome notebook. What to do next: [Open and use an app](notebook_usage.md). + +## If something does not work + +- The installer writes what it did to `menuinst_debug.log` in the install folder. +- See [Troubleshooting an installed app](troubleshooting_installed_app.md), or start from [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/). + +## Update an installed app + +- **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. +- **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, with the `hosts:` line of the app's `labconstrictor-app.yaml`. A program lists the app only if that line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without a `hosts:` line, every program lists the app, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). + +To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## Next + +Open the app and start working: [Open and use an app](notebook_usage.md). diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/notebook_portability.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/notebook_portability.md new file mode 100644 index 0000000..012a0b3 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/notebook_portability.md @@ -0,0 +1,140 @@ +# Write notebooks that run in both Google Colab and JupyterLab + +LabConstrictor ships notebooks as desktop apps built on JupyterLab. At the same time, many collaborators and reviewers prefer Google Colab for quick, cloud-based runs. Writing your notebook to work in both environments makes it easier for users to: + +- **Choose their preferred platform** (Colab in the browser, JupyterLab locally or inside LabConstrictor). +- **Collaborate and review quickly** without forcing everyone to install dependencies. +- **Reproduce results** across cloud and local setups, reducing “works on my machine” issues. +- **Avoid hidden environment assumptions** that only exist in one runtime. + +Below are practical patterns to keep notebooks portable and readable across both runtimes. + +## 1. Keep explanatory text visible when code is hidden + +LabConstrictor apps often hide code cells to present an app-like UI (see [Hide code cells in notebooks](code_hiding.md)). + +If you place `# @title` **at the top of the cell** in Colab, it would give a header to the code cell on Google Colab while remaining visible in local JupyterLab sessions. Follow the example below to keep your notebook clear and user-friendly in both environments: + +```python +# @title Data input + +# Rest of the cell... +``` + +> **Note:** If you need an explanation longer than a line, please use a **Markdown cell** with the explanation. This way, the text is visible everywhere, regardless of code visibility. + +## 2. Guard Colab-only setup code + +Colab-specific setup (mounting Google Drive, installing GPU-only deps, `!pip` installs) should run **only** on Colab. To avoid failures when running locally, wrap it like this: + +```python +import sys + +if 'google.colab' in sys.modules: + print("🚀 Detected Google Colab. Starting installation...") + + !pip install -q "cellpose[all]" tifffile + !pip install -q instanseg-torch + + from google.colab import userdata + from google.colab import drive + + drive.mount('/content/gdrive') + + print("✅ Colab setup done") +else: + # Fallback for local environments + print("⚠️ Not running in Colab. Please ensure dependencies are installed and data paths are set.") +``` + +## 3. Prefer cross-platform paths and storage + +- Use `pathlib.Path` and **relative paths** when possible. +- Avoid hard-coding Colab paths like `/content` or `/content/gdrive` outside guarded blocks. +- For data files, include a **config cell** where users can set a local path or select a file. + +## 4. Avoid Colab-only UI helpers + +Avoid using Colab forms (see [Google's guide to Colab forms](https://colab.research.google.com/notebooks/forms.ipynb)) as they won’t work in JupyterLab. Instead, we recommend using ipywidgets or simple input prompts that work in both environments. This ensures your notebook remains interactive and user-friendly regardless of where it’s run. + +For example, you could turn this Colab form: + +```python +model_name = "Model A" # @param ["Model A", "Model B", "Model C"] +print(f"You selected: {model_name}") +``` + +![Colab form example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/colab.png) + +Into, for example an ipywidgets dropdown that works in both environments: + +**Option A** - with an observable function: + +```python +import ipywidgets as widgets +from IPython.display import display + +model_dropdown = widgets.Dropdown( + options=["Model A", "Model B", "Model C"], + description="Select a model:", + style={'description_width': 'initial'} +) +output = widgets.HTML() + +def on_model_change(change): + if change['type'] == 'change' and change['name'] == 'value': + output.value = f"You selected: {change['new']}" +model_dropdown.observe(on_model_change) + +display(model_dropdown, output) +``` + +![ipywidgets dropdown example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/local_option1.png) + +**Option B** - With a button to confirm the selection: + +```python +import ipywidgets as widgets +from IPython.display import display + +model_dropdown = widgets.Dropdown( + options=["Model A", "Model B", "Model C"], + description="Select a model:", + style={'description_width': 'initial'} +) +confirm_button = widgets.Button(description="Confirm Selection") +output = widgets.HTML() + +def on_confirm_button_click(b): + output.value = f"You selected: {model_dropdown.value}" +confirm_button.on_click(on_confirm_button_click) + +display(model_dropdown, confirm_button, output) +``` + +![ipywidgets dropdown with button example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/local_option2.png) + +As you can see the ipywidgets options require a bit more code, but they work in both environments and are much more versatile in functionality and visualization. + +## 5. Clearly label runtime-specific instructions + +To reduce confusion and keep the flow smooth in both environments, add small callouts in Markdown to guide the user, for example: + +> **Colab users:** Run the `Colab setup` cell first to mount Google Drive. +> +> **JupyterLab users:** Skip the `Colab setup` cell and configure the local data path instead. + +## 6. Test in both environments before release + +Testing both environments before making it public ensures a smooth experience for all users: + +1. Run the notebook end-to-end in **JupyterLab** (or local Jupyter) to validate the LabConstrictor experience. +2. Run the same notebook in **Google Colab** to confirm cloud compatibility. + +--- + +
+ +[🏠 Home](README.md) + +
diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..cec1b8f --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/tools_bridge.md @@ -0,0 +1,78 @@ +# Expose your app's tools to napari, Fiji and QuPath + +Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. Apps that declare no tools are not affected. + +To expose your app's tools: + +1. Put your Python code in `src/` (see [Upload external code](external_code_upload.md)). +2. Declare the tools in a `_lc_tools` module, as shown below. +3. Name the programs your tools work in under `hosts:` in `labconstrictor-app.yaml`. +4. Test the tools, then publish a release. + +How to write a tool, with its inputs, outputs, form layout and tests, is in [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/). What the people who install your app do to run the tools is in [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). + +## What you need + +- An app repository made from this template, with your Python package in `src//`. +- Python functions with type annotations that you want to offer as tools. + +## Declare your tools + +1. Add a module named `_lc_tools` next to your package under `src/` (so `src/mytool_lc_tools/__init__.py` for + the package `mytool`). The installer registers tools only from a module with exactly this name. Declare tools in it with typed + functions, and import your science code **inside** the functions: + + ```python + from typing import Annotated + from labconstrictor_tools import Image, ImageOut, Min, tool + + @tool("Gaussian blur") + def blur(image: Image, sigma: Annotated[float, Min(0)] = 2.0) -> ImageOut: + from mytool.filters import gaussian + return gaussian(image, sigma) + ``` + + Keep the module light: it is imported to read the tool list, so heavy imports at the top slow every start. +2. If you can, import `labconstrictor_tools` only in `_lc_tools`, or inside functions. The rest of your package then also + works where LabConstrictor Tools is not installed: a notebook on Google Colab, a copy of the package used elsewhere, or an installation + where Tools failed to install. +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). + napari, Fiji and QuPath list your app only if `hosts:` names them. +4. Test your tools with `labconstrictor-tools check` and `labconstrictor-tools test`, as + [Writing tools](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/writing-tools/) shows. + +## What the installer does + +When someone installs your app, the installer: + +1. installs your package; +2. if your package has a `_lc_tools` module, installs LabConstrictor Tools; +3. checks that your package can be imported; +4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of + `labconstrictor-app.yaml`. + +When the app is uninstalled, it is unregistered. + +If step 2 or 4 fails, the installer writes a `WARNING` to `menuinst_debug.log` in the install folder, skips the registration and finishes +the installation. The exception is a package that imports `labconstrictor_tools` at the top: then the import check of step 3 fails. + +The installer installs one fixed release of LabConstrictor Tools: the tag in `LC_TOOLS_PIN` of +[app/bash_bat_scripts/post_install.sh](../../app/bash_bat_scripts/post_install.sh) and +[app/bash_bat_scripts/post_install.bat](../../app/bash_bat_scripts/post_install.bat). Template updates move it. To install Tools from +another source (a wheel, a git URL or a mirror), set the environment variable `LC_TOOLS_SPEC` when the installer runs; it replaces the pin. +How Tools releases are made and pinned is in +[Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/#pinning-tools-in-app-installers). + +## Check that it worked + +After you install a release of your app: + +- `menuinst_debug.log` in the install folder says `Tools registered`. +- `labconstrictor-tools list` shows your app and its tools. +- Your app appears in the programs you named under `hosts:`, once their plugin is installed. + +## If something does not work + +- `menuinst_debug.log` in the app's install folder says what the installer did with your tools. +- `labconstrictor-tools doctor` checks the Tools installation, and `labconstrictor-tools logs` shows its log. +- Other problems and their fixes: [Operations](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/tools-operations/). diff --git a/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/workflow_status.md b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/workflow_status.md new file mode 100644 index 0000000..7115b94 --- /dev/null +++ b/.template_sync/resources/v0_1_39_to_v0_1_40/previous/.tools/docs/workflow_status.md @@ -0,0 +1,34 @@ +# Check the status of GitHub workflows + +GitHub Actions runs workflows in your repository: when a notebook or its requirements change (**Updates on notebook change**), when the code in `src/` changes (**Updates on external code change**), when you publish a release (**Build Release Installers**) and every week for template updates (**Sync with Template Repository**, which needs the one-time [`LABCONSTRICTOR_SYNC_TOKEN` setup](template_synchronization.md)). + +## 1. Monitor the progress + +1. Go to the **Actions** tab of your repository. +2. Find the run that matches your latest change or release. +3. Check its status icon: + +![GitHub Actions Status Icons](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/actions_status_icons.png) + +## 2. How to debug a failure + +1. Click the failed run, then the red step: its log says what went wrong. +2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed, with instructions at the top for an AI assistant: paste the whole file into one (such as ChatGPT, Gemini or Claude) and it explains the error and how to fix your notebook or `requirements.yaml`. + +For known errors, see [Troubleshooting repository setup](troubleshooting.md). + +### Best practice for large updates + +The workflows run only on your main branch, so a change is checked once it is merged. For a big update, such as several notebooks or new dependencies, upload one notebook at a time and wait for the green tick before the next: a failure then points to one change. + +--- + +
+ +← Previous            +[🏠 Home](README.md)            +[Next →](troubleshooting.md) + + +
+ diff --git a/.tools/docs/before_getting_started.md b/.tools/docs/before_getting_started.md index 16d81f9..22a82d5 100644 --- a/.tools/docs/before_getting_started.md +++ b/.tools/docs/before_getting_started.md @@ -1,36 +1,12 @@ # Before getting started with LabConstrictor -What LabConstrictor does, and what you need before you create your repository. - ## LabConstrictor in a nutshell -LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. GitHub Actions workflows in your repository do the building. - -### Easy configuration - -A web form sets up your repository (name, version, description, images) and uploads your notebooks with their requirements. You do not edit the workflows yourself. - -### Cross-platform installers - -Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app). - -### Environment management - -Each notebook comes with a `requirements.yaml` file that lists its packages. The workflows merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Helper notebooks generate and check these files for you. - -### Version control - -The first cell of each notebook checks its version. The app's Welcome notebook shows when a newer version of a notebook exists and updates it. - -### User-friendly experience - -The installed app opens JupyterLab with a Welcome notebook that lists your notebooks. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Your repository can be public or private; a private repository cannot be listed in the App Centre. - -### Offline usage +LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. A web form sets up your repository and uploads your notebooks with their requirements; GitHub Actions workflows in your repository do the rest. They merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app). -Once installed, the app runs without internet access, unless your notebooks need it. +The installed app opens JupyterLab with a Welcome notebook that lists your notebooks, shows when a newer version of one exists and updates it. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Once installed, the app runs without internet access, unless your notebooks need it. Your repository can be public or private; a private repository cannot be listed in the App Centre. -## LabConstrictor requirements +## What you need - **A GitHub account**, to create your repository from the template. - **Your Jupyter notebooks.** diff --git a/.tools/docs/code_hiding.md b/.tools/docs/code_hiding.md index 2e9cfce..3caf4dc 100644 --- a/.tools/docs/code_hiding.md +++ b/.tools/docs/code_hiding.md @@ -1,6 +1,6 @@ # Hide code cells in notebooks -LabConstrictor gives the option to hide code cells in Jupyter notebooks, making them cleaner and avoiding overwhelming users with too much code. +If people use your notebook through its widgets rather than by editing Python, you can hide the code and leave the controls visible. ## Who is this for? diff --git a/.tools/docs/external_code_upload.md b/.tools/docs/external_code_upload.md index 883a674..6dde54a 100644 --- a/.tools/docs/external_code_upload.md +++ b/.tools/docs/external_code_upload.md @@ -1,12 +1,12 @@ # Upload external code -If you want to use your own Python modules or scripts in Jupyter notebooks, follow these steps to upload them easily. +Put your own Python code in your repository so that every notebook of your app can import it. ## 1. Prepare your external code -Organize your external code and follow Python packaging best practices. Set up the right folder structure, add an `__init__.py` file, and list any required dependencies. +Put your functions in a package under `src/`: a folder with an `__init__.py` file, so notebooks can import it. List the packages your code needs in your notebooks' requirements. -**Suggested Directory Structure:** +**Suggested folder structure:** ```text src/ @@ -19,9 +19,7 @@ src/ ### What goes in `__init__.py`? -Think of `__init__.py` as the file that tells Python “this folder is a package”. - - If you leave it empty, that is perfectly fine—the package will still import correctly. When you want to make notebooks feel friendlier, you can re-export helper functions so users can discover them more easily: +`__init__.py` tells Python that the folder is a package. It can stay empty. To let notebooks import your main functions directly from the package, re-export them: ```python # src/PYTHON_PROJ_NAME/__init__.py @@ -32,16 +30,17 @@ __all__ = ["run_analysis", "load_config"] Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage. -If you need further readings on `__init__.py`, check out this quick [Geeks for Geeks tutorial](https://www.geeksforgeeks.org/python/what-is-__init__-py-file-in-python/) or the [Real Python guide](https://realpython.com/python-init-py/). +More on `__init__.py`: the [Real Python guide](https://realpython.com/python-init-py/). + ## 2. Upload your external code to the repository -Go to the src folder in your repository and upload your files or folders there. +Open the `src` folder of your repository on GitHub and upload your files or folders there. ![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif) ## 3. How to import into your notebook -Once uploaded, your external code will be available to your notebooks as a package. To use it, import it as shown in the examples below: +Your notebooks import the code as a package: **Import the whole package:** ```python @@ -105,7 +104,7 @@ Then change the variable to `true`: the next release goes to PyPI. Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI. -### Good to know +### Limits and options - **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version. - **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree. diff --git a/.tools/docs/install.md b/.tools/docs/install.md index 9bf667b..8312204 100644 --- a/.tools/docs/install.md +++ b/.tools/docs/install.md @@ -54,9 +54,7 @@ Uninstalling deletes the app's install folder and everything in it: move anythin ## Where the app is listed -If the app ships tools for napari, Fiji or QuPath, the installer registers them with LabConstrictor Tools, with the `hosts:` line of the app's `labconstrictor-app.yaml`. A program lists the app only if that line names it: with `hosts: [notebook, napari]` the app is listed in napari, and not in Fiji or QuPath. Without a `hosts:` line, every program lists the app, and `menuinst_debug.log` in the install folder says so (`'' declares no hosts, so it is listed in every host; ...`). - -To run the tools, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). +Some apps also work inside napari, Fiji or QuPath: the app's page in the App Centre says which. To use them there, install the plugin for your image software once: see [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/). ## Next diff --git a/.tools/docs/migration_0_1_40.md b/.tools/docs/migration_0_1_40.md new file mode 100644 index 0000000..af3f0f6 --- /dev/null +++ b/.tools/docs/migration_0_1_40.md @@ -0,0 +1,38 @@ +# Template 0.1.40: an editorial pass on seven guides + +Design note for the 0.1.40 migration (`.template_sync/migrations/v0_1_39_to_v0_1_40.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 + +A third review of the website found pages that announced what they would explain, narrated their pictures, listed generic benefits or read like a brochure. Two passages also gave readers the wrong thing: + +* `install.md`, a page for app users, explained the `hosts:` line of `labconstrictor-app.yaml` and quoted an installer log message; +* `workflow_status.md` told readers to paste the whole log file into an AI assistant, which "explains the error and how to fix" it: overconfident, and the log can hold tokens and private paths. + +## 2. What changes + +* `notebook_portability.md`: one concrete sentence instead of the benefit list; plainer instructions. +* `before_getting_started.md`: the six feature sections become two paragraphs; the prerequisites (now "What you need"), the token and the `distribution.platforms` sentence of 0.1.39 are kept. +* `external_code_upload.md`: the first step says what to do (a package under `src/` with an `__init__.py`); "Good to know" becomes "Limits and options". +* `code_hiding.md`: a plain first paragraph. +* `install.md`: "Where the app is listed" says only that the app's page in the App Centre names the programs it works in, and links the plugin guide. +* `workflow_status.md`: read the failed step first; an AI assistant can help read the log once tokens, private paths and other sensitive information are removed; check its fix against the error and run the workflow again. +* `tools_bridge.md`: "Apps that declare no tools are not affected" moves from the opening to "What the installer does". + +Commands, file names, behaviour and the anchors other pages link to (`install.md#uninstall-an-app`, `external_code_upload.md#4-publish-the-code-on-pypi-optional`, `code_hiding.md#how-does-the-play-button-work`) do not change. No code changes. + +## 3. What the migration does + +* Each file is replaced by the 0.1.40 page when it is still the template file last shipped, compared with LF line endings (the frozen copies, the 0.1.39 template files, are in `.template_sync/resources/v0_1_39_to_v0_1_40/previous/`). The file keeps its own line endings. +* `external_code_upload.md` is also recognised when the repository form wrote the app's Python package name in place of `PYTHON_PROJ_NAME`; the new page gets the same name. +* A file the app changed is left as it is (`SKIPPED`, with a note of what to change by hand; for most pages nothing is required). `code_hiding.md` and `notebook_portability.md` were changed in the template earlier without a migration, so apps made from an older template have another copy and are skipped. +* A missing file is not created, and nothing is deleted. A second run changes nothing. + +## 4. Adopting it + +Take this template version (the synchronization pull request). For a skipped file, compare it with the template's page; at least make the `workflow_status.md` change by hand. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_40.py`): the resources are the live files and differ from the 0.1.39 ones; a 0.1.39 app reaches the live files with LF and CRLF line endings, and a second run changes nothing; a customised file is skipped with its note; `external_code_upload.md` with a package name; a missing file is not created; the sync from 0.1.39 and the chain from older versions; the anchors other pages link to still exist. +* The older tests compare with the 0.1.39 files (`tests/_v0_1_40.py`, `before_0_1_40`). diff --git a/.tools/docs/notebook_portability.md b/.tools/docs/notebook_portability.md index 012a0b3..6cb4101 100644 --- a/.tools/docs/notebook_portability.md +++ b/.tools/docs/notebook_portability.md @@ -1,19 +1,10 @@ # Write notebooks that run in both Google Colab and JupyterLab -LabConstrictor ships notebooks as desktop apps built on JupyterLab. At the same time, many collaborators and reviewers prefer Google Colab for quick, cloud-based runs. Writing your notebook to work in both environments makes it easier for users to: - -- **Choose their preferred platform** (Colab in the browser, JupyterLab locally or inside LabConstrictor). -- **Collaborate and review quickly** without forcing everyone to install dependencies. -- **Reproduce results** across cloud and local setups, reducing “works on my machine” issues. -- **Avoid hidden environment assumptions** that only exist in one runtime. - -Below are practical patterns to keep notebooks portable and readable across both runtimes. +A LabConstrictor app runs your notebooks in JupyterLab on your colleagues' computers, while a reviewer may open the same notebook in Google Colab without installing anything. These practices keep one notebook working in both. ## 1. Keep explanatory text visible when code is hidden -LabConstrictor apps often hide code cells to present an app-like UI (see [Hide code cells in notebooks](code_hiding.md)). - -If you place `# @title` **at the top of the cell** in Colab, it would give a header to the code cell on Google Colab while remaining visible in local JupyterLab sessions. Follow the example below to keep your notebook clear and user-friendly in both environments: +LabConstrictor apps often hide code cells (see [Hide code cells in notebooks](code_hiding.md)). Put `# @title` on the first line of a cell: Colab shows it as the cell's header, and JupyterLab still shows it as the first line of the cell: ```python # @title Data input @@ -21,11 +12,11 @@ If you place `# @title` **at the top of the cell** in Colab, it would give a hea # Rest of the cell... ``` -> **Note:** If you need an explanation longer than a line, please use a **Markdown cell** with the explanation. This way, the text is visible everywhere, regardless of code visibility. +For an explanation longer than a line, use a Markdown cell: it stays visible everywhere, whether the code is hidden or not. ## 2. Guard Colab-only setup code -Colab-specific setup (mounting Google Drive, installing GPU-only deps, `!pip` installs) should run **only** on Colab. To avoid failures when running locally, wrap it like this: +Run Colab-only setup (mounting Google Drive, installing GPU-only packages, `!pip` installs) only on Colab, so the notebook does not fail on a local computer: ```python import sys @@ -55,9 +46,9 @@ else: ## 4. Avoid Colab-only UI helpers -Avoid using Colab forms (see [Google's guide to Colab forms](https://colab.research.google.com/notebooks/forms.ipynb)) as they won’t work in JupyterLab. Instead, we recommend using ipywidgets or simple input prompts that work in both environments. This ensures your notebook remains interactive and user-friendly regardless of where it’s run. +Colab forms ([Google's guide](https://colab.research.google.com/notebooks/forms.ipynb)) do not work in JupyterLab. Use ipywidgets or simple input prompts instead: they work in both. -For example, you could turn this Colab form: +For example, turn this Colab form: ```python model_name = "Model A" # @param ["Model A", "Model B", "Model C"] @@ -66,7 +57,7 @@ print(f"You selected: {model_name}") ![Colab form example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/colab.png) -Into, for example an ipywidgets dropdown that works in both environments: +into an ipywidgets dropdown: **Option A** - with an observable function: @@ -114,11 +105,11 @@ display(model_dropdown, confirm_button, output) ![ipywidgets dropdown with button example](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/colab_vs_local/local_option2.png) -As you can see the ipywidgets options require a bit more code, but they work in both environments and are much more versatile in functionality and visualization. +These examples need more code than a Colab form, but they work in both Colab and JupyterLab. ## 5. Clearly label runtime-specific instructions -To reduce confusion and keep the flow smooth in both environments, add small callouts in Markdown to guide the user, for example: +When a step differs between the two, say so in a short Markdown note, for example: > **Colab users:** Run the `Colab setup` cell first to mount Google Drive. > @@ -126,10 +117,10 @@ To reduce confusion and keep the flow smooth in both environments, add small cal ## 6. Test in both environments before release -Testing both environments before making it public ensures a smooth experience for all users: +Before you publish a notebook: -1. Run the notebook end-to-end in **JupyterLab** (or local Jupyter) to validate the LabConstrictor experience. -2. Run the same notebook in **Google Colab** to confirm cloud compatibility. +1. Run it from start to end in **JupyterLab** (or local Jupyter), as the app will. +2. Run the same notebook in **Google Colab**. --- diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index cec1b8f..c3c1db8 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -1,6 +1,6 @@ # Expose your app's tools to napari, Fiji and QuPath -Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. Apps that declare no tools are not affected. +Turn functions of your app's Python package into **tools** that people run in napari, Fiji and QuPath, and from the command line. Each tool gets a form made from its function signature. You declare the tools in your repository; the installer registers them on the user's computer. To expose your app's tools: @@ -51,7 +51,7 @@ When someone installs your app, the installer: 4. registers the app (`labconstrictor-tools register ...`) with the version from the `version:` line of `construct.yaml` and the hosts of `labconstrictor-app.yaml`. -When the app is uninstalled, it is unregistered. +When the app is uninstalled, it is unregistered. An app that declares no tools is not affected by any of this. If step 2 or 4 fails, the installer writes a `WARNING` to `menuinst_debug.log` in the install folder, skips the registration and finishes the installation. The exception is a package that imports `labconstrictor_tools` at the top: then the import check of step 3 fails. diff --git a/.tools/docs/workflow_status.md b/.tools/docs/workflow_status.md index 7115b94..6fe84cd 100644 --- a/.tools/docs/workflow_status.md +++ b/.tools/docs/workflow_status.md @@ -13,7 +13,9 @@ GitHub Actions runs workflows in your repository: when a notebook or its require ## 2. How to debug a failure 1. Click the failed run, then the red step: its log says what went wrong. -2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed, with instructions at the top for an AI assistant: paste the whole file into one (such as ChatGPT, Gemini or Claude) and it explains the error and how to fix your notebook or `requirements.yaml`. + The log usually names the command or the package that failed. +2. If the run has an **Artifacts** section at the bottom of its page, download the log file there (a plain `.log` text file, nothing to unzip). It holds the error, the workflow and the script that failed. +3. You can ask an AI assistant to help you read the log; the file starts with instructions for one. First remove tokens, private paths and anything else you would not share. Check any fix it suggests against the error, then run the workflow again. For known errors, see [Troubleshooting repository setup](troubleshooting.md). diff --git a/tests/_v0_1_39.py b/tests/_v0_1_39.py index 3604fb2..c1cb9ec 100644 --- a/tests/_v0_1_39.py +++ b/tests/_v0_1_39.py @@ -10,6 +10,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_40 import before_0_1_40 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_38_to_v0_1_39.py" @@ -25,6 +27,7 @@ def _migration() -> ModuleType: def before_0_1_39(relative: Path | str, data: bytes) -> bytes: """`data` (a live template file at `relative`) without the 0.1.39 change; any other file is returned as it is.""" + data = before_0_1_40(relative, data) migration = _migration() relative = Path(relative) if relative not in migration.FILES: diff --git a/tests/_v0_1_40.py b/tests/_v0_1_40.py new file mode 100644 index 0000000..dfadb8d --- /dev/null +++ b/tests/_v0_1_40.py @@ -0,0 +1,38 @@ +"""Helper of the tests: a live template file as it was before template 0.1.40. + +Template 0.1.40 replaces seven guides in .tools/docs whole (FILES of the migration). The tests of the older migrations compare with +the live files; `before_0_1_40` gives the bytes of a live file without the 0.1.40 change (the frozen 0.1.39 copy when the file is the 0.1.40 +page), so they keep checking what they checked. The 0.1.40 changes are tested in test_template_sync_0_1_40.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_39_to_v0_1_40.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_40_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_40(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the 0.1.40 change; 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" + # Only the 0.1.40 page 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 + previous = (migration.PREVIOUS_ROOT / relative).read_bytes().decode("utf-8").replace("\r\n", "\n") + return previous.replace("\n", newline).encode("utf-8") diff --git a/tests/test_template_sync_0_1_39.py b/tests/test_template_sync_0_1_39.py index 5ee68ca..c6918d4 100644 --- a/tests/test_template_sync_0_1_39.py +++ b/tests/test_template_sync_0_1_39.py @@ -15,6 +15,7 @@ from types import ModuleType from _v0_1_38 import before_0_1_38 +from _v0_1_40 import before_0_1_40 ROOT = Path(__file__).resolve().parents[1] @@ -40,7 +41,8 @@ def lf(path: Path) -> str: def live(relative: Path) -> bytes: - return (ROOT / relative).read_bytes() + """The 0.1.39 template file: the live file without the 0.1.40 change (tests/_v0_1_40.py).""" + return before_0_1_40(relative, (ROOT / relative).read_bytes()) def previous(relative: Path) -> bytes: diff --git a/tests/test_template_sync_0_1_40.py b/tests/test_template_sync_0_1_40.py new file mode 100644 index 0000000..b9d522a --- /dev/null +++ b/tests/test_template_sync_0_1_40.py @@ -0,0 +1,233 @@ +"""Tests of the 0.1.40 migration: the edited guides replace the 0.1.39 guides that an app has not changed.""" +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_39 import before_0_1_39 + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_39_to_v0_1_40.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" +EXTERNAL_CODE_DOC = Path(".tools/docs/external_code_upload.md") +# Anchors that other pages, the code or the website link to. +ANCHORS = { + "install.md": "## Uninstall an app\n", + "external_code_upload.md": "## 4. Publish the code on PyPI (optional)\n", + "code_hiding.md": "## How does the play button work?\n", +} + + +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_40") + + +def lf(path: Path) -> str: + return path.read_bytes().decode("utf-8").replace("\r\n", "\n") + + +def live(relative: Path) -> bytes: + return (ROOT / relative).read_bytes() + + +def previous(relative: Path) -> bytes: + """The 0.1.39 template file (the frozen copy).""" + return (MIGRATION.PREVIOUS_ROOT / relative).read_bytes() + + +def with_version(text: str, version: str) -> str: + """A copy of the template's .template_sync manifest whose template_version is `version` (sync.py refuses another target).""" + return re.sub(r"template_version: [0-9.]+", f"template_version: {version}", text) + + +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\.([4-9][0-9])\b") + self.assertIn(" - from: 0.1.39\n to: 0.1.40\n script: migrations/v0_1_39_to_v0_1_40.py\n", text) + + def test_chains_from_older_versions_reach_0_1_40(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_40") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.38", "0.1.39"): + chain = sync.resolve_migration_chain(manifest["migrations"], start, "0.1.40") + self.assertEqual(chain[-1]["to"], "0.1.40", start) + + def test_the_design_note_exists_and_is_not_in_the_docs_index(self) -> None: + self.assertIn(".tools/docs/migration_0_1_40.md", MIGRATION_PATH.read_text(encoding="utf-8")) + self.assertTrue((DOCS / "migration_0_1_40.md").is_file()) + self.assertNotIn("migration_0_1_40.md", lf(DOCS / "README.md")) + + def test_the_resources_are_the_live_guides_and_the_0_1_39_ones(self) -> None: + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual((MIGRATION.RESOURCE_ROOT / relative).read_bytes(), live(relative)) + self.assertNotEqual(previous(relative), live(relative)) + resources = sorted(p.relative_to(MIGRATION.RESOURCE_ROOT) for p in MIGRATION.RESOURCE_ROOT.rglob("*") if p.is_file()) + expected = sorted([*MIGRATION.FILES, *(Path("previous") / relative for relative in MIGRATION.FILES)]) + self.assertEqual(resources, expected) + + def test_the_older_tests_see_the_0_1_39_guides(self) -> None: + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual(before_0_1_39(relative, live(relative)), before_0_1_39(relative, previous(relative))) + + def test_the_anchors_other_pages_link_to_are_kept(self) -> None: + for name, heading in ANCHORS.items(): + with self.subTest(page=name): + self.assertIn(heading, lf(DOCS / name)) + + def test_the_edited_passages(self) -> None: + install = lf(DOCS / "install.md") + self.assertNotIn("hosts:", install, "app users do not need the manifest rules") + self.assertIn("](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/)", install) + status = lf(DOCS / "workflow_status.md") + self.assertNotIn("paste the whole file", status) + self.assertIn("remove tokens, private paths", status) + start = lf(DOCS / "before_getting_started.md") + self.assertNotIn("### ", start, "the feature sections are condensed") + for kept in ("or only the systems you list under `distribution.platforms`", "](personal_access_token.md)", "## What you need"): + self.assertIn(kept, start) + self.assertNotIn("Apps that declare no tools are not affected.", lf(DOCS / "tools_bridge.md").split("## What you need")[0]) + self.assertNotIn("Good to know", lf(DOCS / "external_code_upload.md")) + self.assertNotIn("makes it easier for users to", lf(DOCS / "notebook_portability.md")) + + def test_the_relative_links_of_the_guides_resolve(self) -> None: + for relative in MIGRATION.FILES: + for target in re.findall(r"\]\(([^)#\s]+)(?:#[^)]*)?\)", lf(ROOT / relative)): + if "://" in target: + continue + with self.subTest(file=str(relative), target=target): + self.assertTrue(((ROOT / relative).parent / target).resolve().exists()) + + +class MigrationTests(unittest.TestCase): + def setUp(self) -> None: + self.repo = Path(tempfile.mkdtemp(prefix="lc_0_1_40_")) + for relative in MIGRATION.FILES: + self.put(relative, previous(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 assert_template_state(self) -> None: + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual((self.repo / relative).read_bytes().replace(b"\r\n", b"\n"), live(relative)) + + def test_an_app_of_0_1_39_gets_the_guides_and_a_second_run_changes_nothing(self) -> None: + log = self.run_migration() + self.assert_template_state() + 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) + self.assert_template_state() + + def test_crlf_is_kept(self) -> None: + for relative in MIGRATION.FILES: + self.put(relative, previous(relative).replace(b"\n", b"\r\n")) + log = self.run_migration() + self.assertNotIn("SKIPPED", log) + self.assert_template_state() + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertNotIn(b"\n", (self.repo / relative).read_bytes().replace(b"\r\n", b"")) + + def test_a_customised_guide_is_skipped_with_a_note_and_the_others_change(self) -> None: + relative = Path(".tools/docs/workflow_status.md") + own = previous(relative) + b"\n## Our own checks\n\nOur own steps.\n" + page = self.put(relative, own) + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised (not the 0.1.39 template file)", log) + self.assertIn("By hand: if the page tells readers to paste the log file into an AI assistant", log) + self.assertEqual(page.read_bytes(), own) + self.assertIn(f"done: {len(MIGRATION.FILES) - 1} file(s) changed", log) + + def test_the_external_code_guide_with_the_package_name(self) -> None: + relative = EXTERNAL_CODE_DOC + self.assertIn("PYTHON_PROJ_NAME", previous(relative).decode("utf-8")) + page = self.put(relative, previous(relative).replace(b"PYTHON_PROJ_NAME", b"celltools")) + log = self.run_migration() + self.assertIn(f"{relative}: updated: replaced by the 0.1.40 page (with the package name celltools)", log) + self.assertEqual(page.read_bytes(), live(relative).replace(b"PYTHON_PROJ_NAME", b"celltools")) + self.assertIn(f"{relative}: unchanged: already up to date", 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_and_kept(self) -> None: + relative = Path(".tools/docs/before_getting_started.md") + self.put(relative, b"\xff\xfe not utf-8") + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED", log) + self.assertEqual((self.repo / relative).read_bytes(), b"\xff\xfe not utf-8") + + def sync(self, start: str) -> subprocess.CompletedProcess[str]: + manifest = self.repo / ".template_sync/manifest.yaml" + if not manifest.exists(): + 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.40 (later templates add migrations). + manifest.write_text(with_version(manifest.read_text(encoding="utf-8"), "0.1.40"), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", start, "--to-version", "0.1.40", "--repository-root", str(self.repo)] + env = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"} + return subprocess.run(command, capture_output=True, text=True, env=env, check=False) + + def test_the_sync_script_runs_the_migration_from_0_1_39(self) -> None: + result = self.sync("0.1.39") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.40]", result.stdout) + self.assert_template_state() + again = self.sync("0.1.39") + self.assertIn("[migration 0.1.40] done: no repository changes were required", again.stdout) + + def test_the_sync_chain_from_0_1_38_reaches_the_live_guides(self) -> None: + """0.1.39 replaces the 0.1.38 before_getting_started.md, then 0.1.40 replaces it again.""" + relative = Path(".tools/docs/before_getting_started.md") + self.put(relative, before_0_1_39(relative, previous(relative))) + self.assertNotEqual((self.repo / relative).read_bytes(), previous(relative)) + result = self.sync("0.1.38") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertNotIn("SKIPPED", result.stdout) + self.assert_template_state() + + +if __name__ == "__main__": + unittest.main()