diff --git a/.template_sync/manifest.yaml b/.template_sync/manifest.yaml index 6f4bced..92285f2 100644 --- a/.template_sync/manifest.yaml +++ b/.template_sync/manifest.yaml @@ -1,4 +1,4 @@ -template_version: 0.1.37 +template_version: 0.1.38 migrations: - from: 0.0.0 to: 0.0.1 @@ -117,3 +117,6 @@ migrations: - from: 0.1.36 to: 0.1.37 script: migrations/v0_1_36_to_v0_1_37.py + - from: 0.1.37 + to: 0.1.38 + script: migrations/v0_1_37_to_v0_1_38.py diff --git a/.template_sync/migrations/v0_1_37_to_v0_1_38.py b/.template_sync/migrations/v0_1_37_to_v0_1_38.py new file mode 100644 index 0000000..56229b7 --- /dev/null +++ b/.template_sync/migrations/v0_1_37_to_v0_1_38.py @@ -0,0 +1,141 @@ +"""Template 0.1.37 -> 0.1.38: the guides for app users and the update guide are merged, and several guides get clearer. + +Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_38.md + +notebook_usage.md becomes "Open and use an app", the one first-run page for app users (it takes in the website's page of that name). +keep_app_up_to_date.md is merged into template_synchronization.md, now titled "Keep your app up to date", and becomes a short pointer +page. The token, requirements, installed-app troubleshooting, installer and manifest guides are made clearer, and the docs README drops +the merged page. + +What this changes in an app repository: each file in FILES is replaced by the 0.1.38 page when it is still the 0.1.37 template file +(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). +That includes keep_app_up_to_date.md, which becomes the pointer page only when it is the 0.1.37 template copy, and .tools/docs/README.md +(in most apps the repository form replaced it with the template's README, so 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_38.md" +TAG = "[migration 0.1.38]" +RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_37_to_v0_1_38" +PREVIOUS_ROOT = RESOURCE_ROOT / "previous" + +DOCS = Path(".tools/docs") +EXTERNAL_CODE_DOC = DOCS / "external_code_upload.md" + +DOCS_INDEX = DOCS / "README.md" +POINTER_PAGE = DOCS / "keep_app_up_to_date.md" + +# Files replaced whole, only when they are the 0.1.37 template file (compared with LF line endings). +FILES = tuple( + DOCS / name + for name in ( + "README.md", + "app_manifest.md", + "before_getting_started.md", + "create_repository.md", + "executable_creation.md", + "external_code_upload.md", + "install.md", + "keep_app_up_to_date.md", + "notebook_requirements.md", + "notebook_upload.md", + "notebook_usage.md", + "personal_access_token.md", + "template_synchronization.md", + "tools_bridge.md", + "troubleshooting.md", + "troubleshooting_installed_app.md", + ) +) + +# What to change by hand in a customised file, by file (added to the SKIPPED note). +BY_HAND = { + DOCS_INDEX: ( + "if it lists keep_app_up_to_date.md, remove that entry (template_synchronization.md is now the update guide, " + 'titled "Keep your app up to date"), and notebook_usage.md is now titled "Open and use an app"' + ), + POINTER_PAGE: "its content is now in template_synchronization.md; you can replace it with a link to that page", +} + +# 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.38 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.37 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.38 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.38 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.37 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.38 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_37_to_v0_1_38/.tools/docs/README.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/README.md new file mode 100644 index 0000000..82e0fc5 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/README.md @@ -0,0 +1,39 @@ +# Internal LabConstrictor documentation + +This file temporarily lists all internal LabConstrictor documentation. After you set up and customise the repository, it will be replaced by the [main README.md](../../README.md) file. + +## From zero to installed notebooks + +- [Before getting started](before_getting_started.md) +- [Create a new repository from this template](create_repository.md) +- [Initialise your repository](initialise_repository.md) +- [Accept a Pull Request](accept_pull_request.md) +- [Generate notebook requirements](notebook_requirements.md) +- [Upload your notebooks](notebook_upload.md) +- [Create executable installers](executable_creation.md) +- [Install an app](install.md) +- [Download and install the application](download_executable.md) (this file will be available after creating executables) +- [Open and use an app](notebook_usage.md) +- [Troubleshooting an installed app](troubleshooting_installed_app.md) + +## Customise and share (optional) + +- [Customise the installer images](installer_images.md) +- [Describe your app for the App Centre](app_manifest.md) +- [Upload external code, and publish it on PyPI (optional)](external_code_upload.md) +- [Expose tools to napari, Fiji and QuPath](tools_bridge.md) + +## Keep your app up to date (optional) + +- [Keep your app up to date](template_synchronization.md) + +## Notebook authoring tips + +- [Write notebooks that run in both Google Colab and JupyterLab](notebook_portability.md) +- [Hide code cells in notebooks](code_hiding.md) + +## GitHub management + +- [GitHub actions/workflows overview](workflow_status.md) +- [Troubleshooting repository setup](troubleshooting.md) +- [Create a personal access token for notebook access](personal_access_token.md) diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/app_manifest.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/app_manifest.md new file mode 100644 index 0000000..677c911 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/app_manifest.md @@ -0,0 +1,200 @@ +# Describe your app: the `labconstrictor-app.yaml` file + +`labconstrictor-app.yaml` is a small text file in the root of your repository. It says what your app is, in your own words. You write it once and keep it up to date yourself. + +Three things read it: + +- **The [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/)** builds your app's card and page from it. +- **Your release workflow** reads `platforms` to decide which installers to build. +- **Your installer** passes `hosts` and `host_requirements` to napari, Fiji and QuPath, so they know whether to list your app. + +Version numbers and download links are not in the file. They always come from your latest GitHub release. + +## Step 1: get the file + +The [repository initialiser](initialise_repository.md) asks for a one-sentence summary, the kind of app and the software it also works in. It adds the file to the initialisation pull request. Read it there and edit it if you like. + +If you skipped that section, or your repository is older than the file, create `labconstrictor-app.yaml` in the root of your repository and paste the minimal example below. The [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) also has a form that writes the file for you and checks it as you type. + +## Step 2: start with the minimal file + +These five fields are required. This file is complete and valid: + +```yaml +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +kind: analysis +distribution: + installer: true +``` + +## Step 3: add what helps people choose your app + +A fuller example. Everything after `distribution` is optional. + +```yaml +# yaml-language-server: $schema=https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +description: |- + A few paragraphs of plain text. + + Separate paragraphs with a blank line. +kind: analysis +hosts: [notebook, napari, qupath] +host_requirements: + napari: + min_version: 0.1.0-alpha.5 + why: Older plugins do not show the outlines + required: false +distribution: + installer: true + platforms: [windows-x86_64, macos-arm64, linux-x86_64] + colab: + - label: Notebook + url: https://colab.research.google.com/github/you/my-app/blob/main/notebooks/App/App.ipynb + pip: my-app +status: Available +license: MIT +authors: + - name: Ada Lovelace + orcid: 0000-0002-1825-0097 +doi: 10.1371/journal.pbio.3002740 +inputs: + - 2D TIFF images, one channel per file +outputs: + - Label masks and a CSV table +limitations: + - Not tested on 3D data +quickstart: + - Open the app and run the Welcome notebook. +categories: [nuclei, counting] +homepage: https://github.com/you/my-app +docs_url: https://github.com/you/my-app#readme +icon: app/logo/logo.png +screenshots: + - path: docs/screenshot.png + caption: The result table next to the segmented image +``` + +The first line lets editors with YAML support (for example VS Code) check the file as you type. Everything is plain text: no HTML and no Markdown. + +## The fields + +| Field | Required | What it does | Example | +|---|---|---|---| +| `schema` | Yes | The format version. Always `1`. | `1` | +| `name` | Yes | The name people know the app by (2 to 60 characters). | `My App` | +| `summary` | Yes | One sentence for the app card (20 to 200 characters). | `Counts nuclei in 2D images.` | +| `kind` | Yes | What the app is for. One of `analysis`, `segmentation`, `simulation`, `game`, `training`, `utility`. It drives the filter in the App Centre. | `analysis` | +| `distribution` | Yes | How people get the app. At least one of `installer`, `colab`, `pip`. See below. | `installer: true` | +| `hosts` | No | Where the app's tools run: `notebook`, `napari`, `fiji`, `qupath`. See below. | `[notebook, napari]` | +| `host_requirements` | No | The oldest napari, Fiji or QuPath plugin your tools need. See below. | | +| `description` | No | A few paragraphs for the app page (up to 2000 characters). | | +| `status` | No | `Experimental`, `Available` or `Deprecated`. | `Available` | +| `license` | No | The licence, as an SPDX name. | `MIT` | +| `authors` | No | A list of people: `name`, and optionally `orcid`. | `- name: Ada Lovelace` | +| `doi` | No | The DOI of the paper to cite, not of a software archive. The app page shows it as the citation. | `10.1371/journal.pbio.3002740` | +| `inputs`, `outputs`, `limitations` | No | Short lists for the app page: one to six lines of 5 to 200 characters each. | `- 2D TIFF images` | +| `quickstart` | No | Up to six short steps for a first run. | `- Open the app.` | +| `categories` | No | Up to six words a scientist would search for. | `[nuclei, counting]` | +| `homepage`, `docs_url` | No | Web addresses. They must start with `https://`. | | +| `icon` | No | A square PNG in your repository. SVG is not accepted. | `app/logo/logo.png` | +| `screenshots` | No | One to six pictures in your repository (PNG, JPG or GIF), each with a `path` and a `caption`. The caption is also the text for screen readers. | | + +The App Centre asks for a few optional fields: `status`, `quickstart`, `screenshots`, a licence, and `inputs` and `outputs` for analysis, segmentation and simulation apps. Without them your app is still listed; its page says "Not stated" or leaves that part out. + +### `distribution`: how people get the app + +| Key | What it does | +|---|---| +| `installer: true` | Your latest GitHub release carries the installers LabConstrictor builds. | +| `platforms` | The systems you support. Needs `installer: true`. Only these installers are built and offered. | +| `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | +| `pip` | The name of your package on PyPI. | + +`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but they build nothing yet: no installer is made for them, and a list with only these two stops the release. + +### `hosts`: where your tools are offered + +This field matters only if your app [exposes tools](tools_bridge.md). napari, Fiji and QuPath list your app only if you name them here. Write the hosts you have tested the app in. + +- `hosts: [notebook]` means no plugin lists the app. Its tools still work in the notebook and on the command line. +- Without a `hosts` line, every plugin lists the app. Say what you mean instead. +- Names are lower case. The check refuses a misspelt, repeated or capitalised name. + +## Plugin versions your tools need (optional) + +If your tools rely on a fix or a feature of the napari, Fiji or QuPath plugin that older plugins lack, say so with `host_requirements`. People with an older plugin keep seeing your app, with one sentence saying which plugin to update and where; your app page on the App Centre lists the versions under "Plugin versions". + +```yaml +host_requirements: + qupath: + min_version: 0.1.0-alpha.7 # a release tag of the plugin, with or without v + features: [shapes_owner_v1] # optional: a host feature id + why: Replace keeps your own annotations # optional: one line shown to the person + fiji: + min_version: 0.1.0-alpha.7 +``` + +- Name only `napari`, `fiji` or `qupath`: the notebook ships with your app and needs no plugin. +- Each needs `min_version`, `features`, or both. `required: true` makes an older plugin refuse your tools instead of warning; use it only when they really fail there. +- Write it as a block, as above. The installer passes this file to `labconstrictor-tools register`, which refuses a malformed block (a misspelt host or key, a version like `latest`); `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml` shows what it read. +- The feature ids and the rule are in [the protocol reference](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/protocol/#host-requirements-which-plugin-an-app-needs). + +## The automatic check + +The **Check App Centre manifest** workflow runs when you change the file and when you publish a release: + +- If the file is missing, it shows a warning and passes. +- If the file is invalid, it fails and says what to fix. This never stops your installers from being built. +- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](template_synchronization.md). +- It also checks that the icon and screenshots you name exist in the repository. + +## Check it yourself + +To check the file before you push: + +1. **On your computer.** From the root of your repository: + + ```bash + pip install pyyaml jsonschema + python .tools/python/check_app_manifest.py + ``` + +2. **In your browser.** Paste your values into the form on the [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). It checks them against the same schema. + +If your app exposes tools, also run `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml`. It prints the `hosts` and `host_requirements` it read, which is what the installer will register. + +The rules themselves are in the [schema](https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json). Your repository has a copy in `.tools/schema/`, and the check uses that copy. + +## Common mistakes + +| What the check says, or what you see | Fix | +|---|---| +| A field "is not allowed" or is "unexpected" | The name is misspelt, or it is at the wrong level. For example `platforms` belongs under `distribution`. | +| `summary` is too short or too long | Write one sentence of 20 to 200 characters. | +| `platforms` without `installer` | Add `installer: true`. `platforms` only applies to installers. | +| The icon or a screenshot is "not found" | The path starts at the root of your repository, with no leading `/`. The file must be committed. | +| A Colab link is refused | The address must start with `https://colab.research.google.com/`. | +| `min_version: 0.2` is refused | YAML reads `0.2` as a number. Put it in quotes: `"0.2"`. | +| Your app is missing from napari, Fiji or QuPath | The host is not in `hosts`, or the app was installed before you added it. Publish a release and install it again. | +| The check passes but nothing changes in the App Centre | The App Centre reads the file from your default branch and updates once a day. | +| Text shows `**stars**` or tags | The fields are plain text. Remove Markdown and HTML. | + +## Get listed + +Having the file does not list your app by itself. To list it, [submit your repository](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) to the App Centre. You do this once: later releases appear by themselves. + +--- + +
+ +[← Previous](installer_images.md)            +[🏠 Home](README.md)            +[Next β†’](external_code_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..cbbed46 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.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 for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor). + +### 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_37_to_v0_1_38/.tools/docs/create_repository.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/create_repository.md new file mode 100644 index 0000000..39347c4 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/create_repository.md @@ -0,0 +1,33 @@ +# Create your repository + +Your app lives in its own GitHub repository, made from the LabConstrictor template. + +1. Open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor). +2. Click the green **Use this template** button at the top right, then **Create a new repository**. + + ![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) + +3. Fill in the details: + - **Include all branches:** leave it off. + - **Owner:** your personal account or your research group's organization. + - **Repository name:** a short name, for example `MyLabTools`. We recommend using it as your app's name when you initialise the repository. + - **Description** (optional): what your notebooks do, for example "Automated cell migration analysis". + - **Visibility:** **Public** to share your installers right away; **Private** to keep the code within your lab while you work on it. A private repository cannot be listed in the App Centre: make it public before you submit your app. +4. Click **Create repository**. + +Next: [Initialise your repository](initialise_repository.md). + +## Template updates (optional, later) + +The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](template_synchronization.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. + +--- + +
+ +[← Previous](before_getting_started.md)            +[🏠 Home](README.md)            +[Next β†’](initialise_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/executable_creation.md new file mode 100644 index 0000000..5194968 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/executable_creation.md @@ -0,0 +1,56 @@ +# Create installer files + +Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release. + +## What you need + +- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md). +- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`). + +## Check before you release + +- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on. +- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)). + +## 1. Draft a new release + +1. Go to your repository's main page. +2. Click **Releases** (in the right sidebar). +3. Click **Create a new release** and fill in: + - **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it. + - **Release title**: for example `Initial release`. + - **Description** (optional): what is new in this release. + +## 2. Publish the release + +Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system. + +## Check that it worked + +- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)). +- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `--` (for example `MyApp-0.0.1-Windows-x86_64.exe`). +- `.tools/docs/download_executable.md` in your repository now has download buttons for this release. + +## If something does not work + +- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section. +- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again. +- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md). + +## 3. After the release + +- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md). +- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). +- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md). + + +--- + +
+ +[← Previous](notebook_upload.md)            +[🏠 Home](README.md)            +[Next β†’](installer_images.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..883a674 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.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_37_to_v0_1_38/.tools/docs/install.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/install.md new file mode 100644 index 0000000..9bf667b --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.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_37_to_v0_1_38/.tools/docs/keep_app_up_to_date.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/keep_app_up_to_date.md new file mode 100644 index 0000000..e97da7f --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/keep_app_up_to_date.md @@ -0,0 +1,3 @@ +# Keep your app up to date + +This page has moved: see [Keep your app up to date](template_synchronization.md). diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_requirements.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_requirements.md new file mode 100644 index 0000000..291f485 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_requirements.md @@ -0,0 +1,117 @@ +# Generate the requirements of your notebook + +Every notebook you upload needs a `requirements.yaml` file: the Python version and the packages it uses, each with its exact version. The installer installs these packages on your users' computers. + +The upload form accepts only exact versions: every dependency must have the form `package==version`. Version ranges such as `numpy>=1.24` can only appear in a `requirements.yaml` that you edit directly in your repository on GitHub, without the form (see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package)). + +There are two ways to make the file: + +* **Option 1 (automated):** the Requirements Generator notebook reads the packages from the Python environment where your notebook runs. Use it when you start from scratch. +* **Option 2 (manual):** you write the file yourself and check it with the Requirements Validator notebook. Faster if you already have a `requirements.txt` with versions. + +## What you need + +- Your notebook, running without errors in a Python environment: on your computer (conda or virtualenv) or in Google Colab. +- For Option 1 on your computer: that same environment, with Jupyter. The generator must run in the environment your notebook uses, because it reads the package versions from it. + +## Option 1: Automated extraction of requirements + +### 1. Open the Requirements Generator notebook + +Open it where your notebook runs: + +* **On your computer:** download [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) (with the download button shown below) and open it in the environment you use for your notebook. If you have several conda environments, use the one your notebook runs in. + + ![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) + +* **Google Colab:** open the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). Colab runs each notebook in its own session, so the packages your notebook installs must be installed in the generator's session too: the generator finds your notebook's `pip install` commands and offers a cell that runs them. + +### 2. Run the Requirements Generator + +Run its cells in order and follow the instructions in the notebook: choose your notebook, add helper files your notebook uses if any, then generate the file. It saves `_requirements.yaml` next to the generator (in Colab it is also downloaded). You can upload it with that name: the upload form saves it as `requirements.yaml`. + +## Option 2: Manual extraction of requirements + +### 1. Create a `requirements.yaml` file + +Start from the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). It has three fields: + +* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). +* **`python_version`:** the Python version the notebook runs with (for example `3.11.1`). All notebooks of an app must use the same one. +* **`description`:** one sentence on what the notebook does. + +```yaml +dependencies: + - pandas==2.2.2 + - ipython==7.34.0 + - tqdm==4.67.1 +description: This notebook is for analyzing cell migration data... +python_version: 3.11.1 +``` + +### 2. Check it with the Requirements Validator notebook + +* **Google Colab (recommended, nothing to install):** open the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). +* **On your computer:** download [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets`. + +Follow the instructions in the notebook and give it your `requirements.yaml` when it asks. + +## Check that it worked + +- You have a `requirements.yaml` (or `_requirements.yaml`) file. +- Every line under `dependencies` has the form `package==version`, and `python_version` is the version your notebook runs with. + +You are ready to [upload your notebook](notebook_upload.md). + +## If something does not work + +- **A package is missing from the generated file.** The generator finds only packages installed in the environment it runs in. Open it in the environment of your notebook, or add the package by hand with its version. +- **The upload form says "Dependency '...' is not in the correct format".** Fix that line to `package==version`. +- **The workflow stops after the upload with conflicting versions.** Two notebooks ask for different versions of a package: see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package). + +## What happens after you upload: the lock file + +When a notebook and its `requirements.yaml` reach the repository, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt`, plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`. + +The installer uses `requirements_gpu.txt` when it finds an NVIDIA GPU on Windows or Linux. In that file `tensorflow` becomes `tensorflow[and-cuda]` on Linux only: TensorFlow has had no Windows GPU build since version 2.10, and its CUDA packages exist only for Linux, so Windows keeps plain `tensorflow` (CPU). + +The workflow then writes a **lock file** next to each requirements file (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. + +* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. +* To move every package to its newest version, delete the `requirements*.lock.txt` files and run the workflow by hand (**Actions > Updates on notebook change > Run workflow**). +* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. + +### When notebooks ask for different versions of a package + +The merge never changes a notebook's requirement silently. Each requirement is kept as written in the notebook's `requirements.yaml`: a version range you wrote there directly on GitHub (`numpy>=1.24`) stays a range, and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: + +* two notebooks pin a package to different versions (`numpy==1.26.4` and `numpy==2.0.0`); +* a pin does not meet another notebook's requirement (`numpy==2.0.0` and `numpy<2`); +* no version meets all the requirements (`numpy<2` and `numpy>=2.1`). + +The log of the **Run merge script** step names the package, every notebook and its requirement. Then either: + +* **make the notebooks agree:** change their `requirements.yaml` to a version that works for every notebook; or +* **decide explicitly** in `requirements_overrides.yaml`, at the top of the repository, which requirement every notebook gets, and why: + +```yaml +overrides: + numpy: + use: "==2.0.0" + reason: "Notebook A was re-run with numpy 2.0.0 and gives the same results; notebook B needs 2.0." +``` + +The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. + +Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. + +--- + +
+ +[← Previous](accept_pull_request.md)            +[🏠 Home](README.md)            +[Next β†’](notebook_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_upload.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_upload.md new file mode 100644 index 0000000..d28a966 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_upload.md @@ -0,0 +1,193 @@ +# Add or update a notebook + +Upload a notebook and its `requirements.yaml` to your repository with the LabConstrictor web form. The form opens a pull request; when you merge it, GitHub checks that the notebook's packages can be installed together. + +## What you need + +- An initialised repository: see [Initialise your repository](initialise_repository.md). +- Your notebook (`.ipynb`) and its requirements file: see [Generate the requirements of your notebook](notebook_requirements.md). +- A GitHub personal access token (classic, it starts with `ghp_`): see [Generate a GitHub personal access token](personal_access_token.md). + +## 1. Prepare your notebook + +The first cell of every notebook checks its version, so users see when a newer version exists. + +1. Add a code cell at the top of your notebook (see this [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help), and paste the code below into it. +2. Set `current_version` to the version of your notebook (for example `"0.0.2"`) and `notebook_name` to the name of the notebook file without `.ipynb`. + +> Each time you change what the notebook does, increase `current_version` so users can see there is a new version. + +```python +# @markdown Run this cell to check this notebook's version. + +current_version = "0.0.1" +notebook_name = "Notebook_template" # Replace with the actual notebook name + +# First of all check if ipywidgets is installed, if not throw an informative error +try: + import ipywidgets as widgets +except ImportError: + raise ImportError("ipywidgets is not installed. Please install it using 'pip install ipywidgets' or 'conda install -c conda-forge ipywidgets'.") + +from IPython.display import display + +try: + from google.colab import output + output.enable_custom_widget_manager() + + try: + import yaml + except ImportError: + raise ImportError("pyyaml is not installed. Please install it using 'pip install pyyaml' or 'conda install -c conda-forge pyyaml'.") + + import requests + import base64 + + # Create widgets + github_repo = widgets.Text( + value="", + description="*GitHub Repository URL:", + placeholder="e.g https://github.com/username/repository", + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + github_token = widgets.Password( + value="", + description="*Personal Access Token:", + placeholder="[Disabled] e.g. ghp_XXXXXXXXXXXXXXXXXXXX", + disabled=True, + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + test_button = widgets.Button( + description="Test Connection", + button_style='success', + ) + + output_area = widgets.HTML() + + # By default the repository is considered public + if "repository_is_private" not in globals(): + repository_is_private = False + elif repository_is_private: + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + + def on_test_button_clicked(b): + global repository_is_private + + # Check that the GitHub repository URL is provided + if not github_repo.value: + output_area.value = "⚠️ Please provide a GitHub repository URL." + return + + # Get the owner and repo name from the URL + repo_url = github_repo.value.rstrip('/') + github_owner, github_repo_name = repo_url.split('/')[-2:] + + # Online version checking file path + version_file_path = "notebooks/notebook_latest_versions.yaml" + version_url = f"https://api.github.com/repos/{github_owner}/{github_repo_name}/contents/{version_file_path}" + + # Do an initial request to check if the repository is public + if not repository_is_private: + version_response = requests.get(version_url) + if version_response.status_code == 404: + repository_is_private = True + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + output_area.value = f"⚠️ We have detected that the repository might be private. Please provide a Personal Access Token and click 'Test Connection' again." + return + else: + headers = {"Accept": "application/vnd.github.v3+json"} + if not github_token.value: + output_area.value = "⚠️ Personal Access Token is required for private repositories." + return + headers["Authorization"] = f"token {github_token.value}" + + version_response = requests.get(version_url, headers=headers) + + # Check the response status + if version_response.status_code == 200: + content = version_response.json()['content'] + decoded_content = base64.b64decode(content).decode('utf-8') + config = yaml.safe_load(decoded_content) + # notebook_latest_versions.yaml groups the notebooks by folder: {"": {"": ""}} + latest_version = next((str(group[notebook_name]) for group in (config or {}).values() + if isinstance(group, dict) and notebook_name in group), "") + + output_area.value = (f"Notebook version: `{current_version}`
" + f"Latest version available: `{latest_version}`
") + + if latest_version == "": + output_area.value += "⚠️ This notebook is not listed in the version file.
" + elif current_version == latest_version: + output_area.value += "βœ… This notebook is up-to-date.
" + else: + output_area.value += f"⚠️ A new version of this notebook is available." + else: + output_area.value += "⚠️ Could not retrieve the version file.
" + + test_button.on_click(on_test_button_clicked) + # Widget layout + widget_box = widgets.VBox([github_repo, github_token, test_button, output_area]) + display(widget_box) +except ImportError: + display(widgets.HTML('To check the notebook version, please go to the Welcome notebook.')) +``` + + +## 2. Generate the requirements file + +Create the `requirements.yaml` file of your notebook: see [Generate the requirements of your notebook](notebook_requirements.md). + +## 3. Upload to the repository + +1. Open the [LabConstrictor form](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. Click **Upload/Update notebook**. +3. Upload your notebook file (`.ipynb`) and its requirements file. +4. Click **βž• Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **πŸ“ƒ Submission list**. Repeat steps 3 and 4 to add more notebooks to the same pull request. +5. Under **⬆️ Upload it to GitHub**, enter your repository's address and your personal access token. +6. Click **πŸš€ Create pull request**. + +## 4. Merge the pull request + +The form opens a pull request titled "Upload/Update notebook" followed by the notebook's name. Merge it: see [Accept a pull request](accept_pull_request.md). The merge starts the workflow **Updates on notebook change**, which merges the requirements of all notebooks, hides the code cells (unless you disabled it) and checks that the packages can be installed. + +## Check that it worked + +- In the **Actions** tab, the run of **Updates on notebook change** has a green tick ([how to read a run](workflow_status.md)). +- Your notebook is in `notebooks//`, next to its `requirements.yaml`. +- `notebooks/notebook_latest_versions.yaml` lists the notebook with its `current_version`. + +You can now [create the installers](executable_creation.md). + +## If something does not work + +- **The form refuses the requirements file.** The message names the line to fix. Each dependency must be `package==version`: see [Generate the requirements of your notebook](notebook_requirements.md). +- **The workflow failed and your merge was undone.** When the merged requirements cannot be installed, the workflow reverts your merge automatically. Open the failed run, find the package that failed in the log, fix the notebook's requirements and upload again. +- **The workflow stops with conflicting versions.** Notebooks ask for different versions of the same package; nothing is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). +- **The version check says "This notebook is not listed in the version file".** `notebook_name` in the first cell does not match the notebook's file name. + +--- + +## How to update an existing notebook + +Updating a notebook works the same way as adding one: + +1. In the first cell of your notebook, increase `current_version` (for example from `1.0.0` to `1.0.1`). +2. If the notebook now uses other packages or versions, generate its requirements file again. +3. Upload the notebook and its requirements file with the [LabConstrictor form](https://labconstrictor-form.streamlit.app/), as above. Keep the notebook's file name exactly the same: a notebook with the same name replaces the old one. + +--- + +
+ +[← Previous](notebook_requirements.md)            +[🏠 Home](README.md)            +[Next β†’](executable_creation.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_usage.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_usage.md new file mode 100644 index 0000000..dea128e --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/notebook_usage.md @@ -0,0 +1,80 @@ +# Open and use an app + +You installed a LabConstrictor app ([how to install](install.md)). From here: open it, try the app's example, then use your own data. + +Want to see the idea first? The [interactive demo](https://cellmigrationlab.github.io/LabConstrictor-Site/demo/) lets you try a notebook, napari and Fiji with example data before you install anything. + +## Open the app + +Start the app from the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux): search for its name and click its icon. + +A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the **Welcome notebook**: + +![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) + +## Open a notebook from the Welcome notebook + +Run the cell of the Welcome notebook. It shows a table of the app's notebooks, with their version and whether a newer version exists. Click **Open the notebook** in the last column to open a notebook in a new tab. + +If the app's repository on GitHub is private, the Welcome notebook asks for a GitHub personal access token to check for new versions: see [Generate a GitHub personal access token](personal_access_token.md). + +## Run a notebook + +Follow the instructions written in the notebook, and run its cells from top to bottom. Notebooks made with LabConstrictor often hide their code. Run a cell with the play button next to it, if there is one, or select the cell and click the play button in the top toolbar: + +![Toolbar Play Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Play_Button.png) + +The **Show/Hide Code** button in the top toolbar shows or hides the code of every cell: + +![Show Hide Code Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_ShowHide_Button.png) + +New to JupyterLab? See [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). + +## Try the app's example + +Look for an example in the app's documentation: the **Documentation** or **README** link on its page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/). If it has one, run it first and compare your result with the one it describes. What an app does, and what its notebooks expect, is described there. + +## Use it in napari, Fiji or QuPath + +Some apps also have **tools**: analyses you run from napari, Fiji or QuPath on the image you have open, with a form for the settings and the results drawn on the image. The app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) shows which programs it works in. Install the plugin for your program once: [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/) explains how. + +## Keep your results + +Each notebook decides where it writes its results. Note the folder it names before you close JupyterLab, and copy what you want to keep. + +## Use it without installing + +Many apps also run in Google Colab. The app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) lists its Colab notebooks and, when it has one, a pip command. + +## Update a notebook + +When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. + +1. Close the notebook's tab first. Otherwise JupyterLab can save the old copy over the new one. +2. Click **Update**, then confirm with **Back up and update**. + +Your current copy, with your changes and outputs, is kept as `.backup-.ipynb` in the same folder. If the download fails, your notebook is not changed. + +## Close the app + +When you have finished, stop JupyterLab with **File > Shut Down** (or click the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. + +## If something does not work + +- Windows and macOS warn about installers that are not code-signed yet, and both have a way to continue: see [Install an app](install.md). +- [Troubleshooting an installed app](troubleshooting_installed_app.md) covers problems with an app on your computer. +- [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/) lists what you may see and where each is explained. +- Open an issue in the app's repository: the **Report a problem** link on its page in the App Centre, when the repository has an issue tracker. + + +--- + + +
+ +[← Previous](download_executable.md)            +[🏠 Home](README.md)            +Next β†’ + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/personal_access_token.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/personal_access_token.md new file mode 100644 index 0000000..404a640 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/personal_access_token.md @@ -0,0 +1,46 @@ +# Generate a GitHub personal access token + +> Looking for the token used by the automatic template update workflow? Follow the dedicated [automatic template synchronization guide](template_synchronization.md). It uses a repository-scoped fine-grained token with a different purpose and secret name. + +A GitHub personal access token lets LabConstrictor act on your repositories as you. You need one for: + +- the [repository initialiser](initialise_repository.md) and the [notebook upload form](notebook_upload.md): they open a pull request in your repository; +- the Welcome notebook, and the version check in the first cell of each notebook, of an installed app whose repository is private: they read the newest notebook versions from the repository (in the Welcome notebook, enter the token and click **Load Private GitHub Repo**). + +The forms accept only a classic token, which starts with `ghp_`, and reject a fine-grained token (it starts with `github_pat_`). A classic token needs the **repo** scope to write to a repository and to read a private one. + +![Gif of generating a GitHub token](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/GitHub_Access_Token.gif) + +## Create the token + +1. Go to https://github.com/ and sign in. +2. Click your profile icon (top right) βž” **Settings**. +3. In the left sidebar, select **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)**. +4. Click **Generate new token** βž” **Generate new token (classic)**. +5. Give your token a descriptive **Note** (for example `LabConstrictor forms`) and set an **Expiration**. We recommend one: an expired token stops working by itself if you forget it. +6. Under **Scopes**, tick **repo**. If all your repositories are public, **public_repo** is enough. +7. Click **Generate token** at the bottom. +8. **Copy** your new token right away. GitHub shows it only once. +9. Paste it where it is asked for: the **Personal Access Token** field of the repository initialiser or of the notebook upload form, or the **Personal Access Token** field of the Welcome notebook or of a notebook's first cell. + +A classic token with the **repo** scope can read and write all your repositories: keep it private, and do not save it in a notebook or a file in your repository. + +## Renew or revoke the token + +Open **Settings** βž” **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)**: + +- **Renew:** click the token's name, then **Regenerate token**, choose a new expiration and copy the new token. The old one stops working. +- **Revoke:** click **Delete** next to the token. Do this as soon as you no longer need it, or if it may have been seen by someone else. + + +--- + + +
+ +[← Previous](troubleshooting.md)            +[🏠 Home](README.md)            +Next β†’ + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/template_synchronization.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/template_synchronization.md new file mode 100644 index 0000000..9b5436c --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/template_synchronization.md @@ -0,0 +1,92 @@ +# Keep your app up to date + +The LabConstrictor template keeps improving. Your repository can receive those improvements, including updates to its GitHub Actions workflows, as a pull request that you review and merge. This is optional and can wait until after your first release. + +## How it works + +The **Sync with Template Repository** workflow runs every Monday at 09:00 UTC, and you can also start it yourself from the **Actions** tab. When the template has a newer version than your repository, the workflow applies the changes needed to move your repository to that version and opens a pull request titled "Sync template to version" followed by the new version number. You then merge it as described in [Accept a pull request](accept_pull_request.md). When your repository is already on the latest template version, the run ends without opening a pull request. + +Template-managed files, such as the copy of the App Centre manifest schema used by the **Check App Centre manifest** workflow, are refreshed by the same pull request. If that check rejects a field the App Centre accepts, your copy of the schema is older than the App Centre: merge the latest sync pull request. + +To open that pull request, the workflow needs a token that you create once and save in your repository as the secret `LABCONSTRICTOR_SYNC_TOKEN`. The token gives access only to the repository you select, not to your other repositories. Without it, the workflow stops with the error "Synchronization setup required" as soon as a newer template version exists, and your repository stays on the template version it has. + +## What you need + +- Admin access to your app's repository on GitHub (to add a secret). + +## Step 1: Create the synchronization token + +![GIF showing the token creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Token_Creation.gif) + +Open [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write), which fills in most of the form, then: + +1. Under **Resource owner**, select the owner of your repository. +2. Under **Repository access**, select **Only select repositories**, then select your repository. +3. Choose an expiration period. The link suggests 365 days. +4. Check these repository permissions: + - **Contents:** Read and write + - **Pull requests:** Read and write + - **Workflows:** Read and write +5. Select **Generate token**. +6. Copy the token. + +> GitHub shows the token only once. Keep the page open until you have saved it in Step 2. + +## Step 2: Save the token as a repository secret + +![GIF showing the secret creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Secret_Creation.gif) + +1. Open your repository. +2. Select **Settings**. +3. In the left sidebar, select **Secrets and variables**, then **Actions**. +4. Select **New repository secret**. +5. Enter this exact name: + + ```text + LABCONSTRICTOR_SYNC_TOKEN + ``` + +6. Paste the token into the **Secret** field. +7. Select **Add secret**. + +GitHub encrypts repository secrets: the token is not shown in the repository or in the workflow logs. + +## Check that it worked + +Open the **Actions** tab, select **Sync with Template Repository** and click **Run workflow**. The run ends with a green tick. If a newer template version exists, a pull request titled "Sync template to version ..." appears in the **Pull requests** tab: merge it as described in [Accept a pull request](accept_pull_request.md). + +## Repositories created before template version 0.1.12 + +The older synchronization workflow does not use `LABCONSTRICTOR_SYNC_TOKEN`. If a run failed with an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, edit the workflow once: + +1. Open [`.github/workflows/sync_template.yml`](../../.github/workflows/sync_template.yml) in your repository. +2. Select the pencil icon to edit the file. +3. Replace all its lines with those of the [template's workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). +4. Select **Commit changes** and commit directly to the default branch. +5. Run **Sync with Template Repository** again. + +The next template update then keeps the workflow up to date by itself. + +## Renewing an expired token + +When the token expires, runs fail with an authentication error such as "Bad credentials". Then: + +1. Create a new token as in Step 1. +2. Open **Settings β†’ Secrets and variables β†’ Actions**. +3. Select `LABCONSTRICTOR_SYNC_TOKEN`. +4. Select **Update secret** and paste the new token. +5. Run **Sync with Template Repository** again. + +## If something does not work + +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions), and [Check the status of GitHub workflows](workflow_status.md) for how to read a failed run. + +--- + +
+ +[← Previous](tools_bridge.md)            +[🏠 Home](README.md)            +[Next β†’](notebook_portability.md) + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..cec1b8f --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.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_37_to_v0_1_38/.tools/docs/troubleshooting.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/troubleshooting.md new file mode 100644 index 0000000..4bf8fc9 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/troubleshooting.md @@ -0,0 +1,75 @@ +# Troubleshooting repository setup + +Problems with your repository on GitHub. For problems with an installed app on your computer, see [Troubleshooting an installed app](troubleshooting_installed_app.md). + +## Synchronisation is failing on GitHub Actions + +The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Keep your app up to date](template_synchronization.md). + +### "Synchronization setup required": the token is missing + +Create the token and save it under **Settings β†’ Secrets and variables β†’ Actions** with this exact name: + +```text +LABCONSTRICTOR_SYNC_TOKEN +``` + +### GitHub refuses to update a workflow file + +If the error says GitHub refuses to create or update a workflow without `workflows` permission, check that the token has all of these repository permissions: + +- **Contents:** Read and write +- **Pull requests:** Read and write +- **Workflows:** Read and write + +Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide, so that the workflow uses the secret. + +### Bad credentials or authentication failed + +The token has expired or was revoked. Create a new token and update the `LABCONSTRICTOR_SYNC_TOKEN` secret: see [Renewing an expired token](template_synchronization.md#renewing-an-expired-token). + +## The release stops at "check_placeholders.py" + +Before it builds the installers, the release workflow checks that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer with one would fail on your users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). + +The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. + +## The release stops at "Installers to build" + +The release reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release can build: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [Describe your app for the App Centre](app_manifest.md)), commit, then publish the release again. + +## "The notebooks ask for incompatible package versions" + +The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` step of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). + +If a template update created `requirements_overrides.yaml` for you, its entries keep the versions your app installed until then (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. + +## Publishing to PyPI fails + +The workflow **Publish the Python package to PyPI** (`publish_pypi.yml`) runs at a release only when the repository variable `PYPI_PUBLISH` is `true` or `testpypi` (see [Upload external code](external_code_upload.md#4-publish-the-code-on-pypi-optional)). Its first job checks and builds the package; its second job uploads it. The installers do not depend on it: a failure here leaves the release and its installers as they are. + +| What you see | What to do | +|---|---| +| Both jobs are grey (skipped) | The variable is missing or has another value. It must be a **variable** (Settings > Secrets and variables > Actions > **Variables**), not a secret, named `PYPI_PUBLISH`, with the value `true` or `testpypi` exactly. | +| `invalid-publisher: valid token, but no corresponding publisher` | The trusted publisher on pypi.org (or test.pypi.org for `testpypi`) does not match this workflow. Check the five fields: owner, repository, workflow `publish_pypi.yml`, environment `pypi`, and the project name. Then re-run the failed job (Actions > the run > **Re-run failed jobs**). | +| `... isn't allowed to upload to project ...` (403) | The name belongs to another PyPI project that this repository is not a publisher of. If it is yours, add the publisher in that project's **Publishing** page; if not, choose another `name=` in `setup.py` (and `distribution.pip`). | +| `PyPI already has ` (or `File already exists`) | That version was uploaded before; a version can be uploaded only once, even after it was deleted. Publish a new release with a higher version. | +| `There is no Python package in src/` | Add your code as a folder with an `__init__.py` in `src/` (see [Upload external code](external_code_upload.md)), or delete the variable `PYPI_PUBLISH`. | +| `... also publishes to PyPI` | Another workflow of the repository uploads to PyPI too. Keep one: delete the variable `PYPI_PUBLISH`, or delete the other workflow. | +| `distribution.pip of labconstrictor-app.yaml is ..., but setup.py names the package ...` | Make the two names the same. | +| `PyPI refuses a package whose dependency is a URL` | `setup.py` lists a dependency as `name @ git+https://...`. Publish that dependency on PyPI and name it with a version, or move the URL to `requirements.txt` (the installer still installs it; the PyPI package leaves it out). | +| `setup.py still has the template placeholder ...` | Replace the placeholder in `setup.py` (the log says which), commit, and publish a new release. | +| The upload job waits | The `pypi` environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. | + +After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. + +--- + +
+ +[← Previous](workflow_status.md)            +[🏠 Home](README.md)            +[Next β†’](personal_access_token.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/troubleshooting_installed_app.md b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/troubleshooting_installed_app.md new file mode 100644 index 0000000..e011770 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/.tools/docs/troubleshooting_installed_app.md @@ -0,0 +1,71 @@ +# Troubleshooting an installed app + +Problems with an app on your computer, after you installed it. For problems with your repository on GitHub, see [Troubleshooting repository setup](troubleshooting.md). + +## Where to find the logs + +Two files in the app's install folder (the folder you chose when you installed it) record what happened: + +- `menuinst_debug.log`: what the installer did. +- `launcher_debug.log`: what happened when you opened the app. If the app cannot start, a message names this file. + +Send them along when you ask the app's developer for help. + +## App still appears in the Windows Installed apps list after uninstalling + +On Windows, after you uninstall the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app can stay in the list and refuse to uninstall again, with a message like this: + +![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) + +Uninstall it from the Control Panel instead: + +1. Open the Control Panel. You can search for it in the Windows search bar. +2. Go to `Programs > Programs and Features`. +3. Find the app in the list, right-click it, and select `Uninstall`. +4. A message may say something like "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes`. + +The app is then removed from the list. + +## Windows asks for administrator rights for python.exe while uninstalling + +Uninstalling an older release of an app may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. + +1. Click **No**. The prompt is not needed. +2. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. + +The uninstall then finishes normally, and nothing outside the app folder is changed. **Yes** and **Retry** do not help: the same error comes back. + +Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. + +Newer releases of the app do not have this problem: install the newest release of the app. + +## The notebook fails with "No module named ..." although the installation finished + +The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This can happen with an older release of an app when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. + +Install the newest release of the app: newer releases always use the app's own Python. + +Advanced, if you cannot install a newer release: delete the personal kernel folder. The other Jupyter installations on the computer that use it lose it too. + +- Linux: `~/.local/share/jupyter/kernels/python3` +- macOS: `~/Library/Jupyter/kernels/python3` +- Windows: `%APPDATA%\jupyter\kernels\python3` + +## My changes to a notebook are gone after an update + +The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Older releases of some apps replace the notebook without keeping a copy: install the newest release of the app to get this backup. + +## JupyterLab does not start because Windows reports an ASN.1 certificate error + +A broken certificate in the Windows certificate store can stop JupyterLab from starting. The app's launcher works around it: it first uses the system's certificates and, if one of them cannot be read, falls back to a verified certificate bundle. Certificate checks are never switched off. `launcher_debug.log` says which one was used. + +If your organisation uses its own certificate authority, save its certificates as a PEM file and set one of these environment variables to the path of that file before you install or open the app: + +- `LABCONSTRICTOR_CA_BUNDLE`, for every LabConstrictor app; +- `_CA_BUNDLE`, for one app: the app's name in capitals, with spaces and punctuation replaced by `_` (for the app "My Project", `MY_PROJECT_CA_BUNDLE`). + +To test the launcher without opening JupyterLab, run this in a command prompt (replace `` and ``): + +```text +\python.exe \\launch_jupyter.py --self-test +``` diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/README.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/README.md new file mode 100644 index 0000000..31305e1 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/README.md @@ -0,0 +1,40 @@ +# Internal LabConstrictor documentation + +This file temporarily lists all internal LabConstrictor documentation. After you set up and customise the repository, it will be replaced by the [main README.md](../../README.md) file. + +## From zero to installed notebooks + +- [Before getting started](before_getting_started.md) +- [Create a new repository from this template](create_repository.md) +- [Initialise your repository](initialise_repository.md) +- [Accept a Pull Request](accept_pull_request.md) +- [Generate notebook requirements](notebook_requirements.md) +- [Upload your notebooks](notebook_upload.md) +- [Create executable installers](executable_creation.md) +- [Install an app](install.md) +- [Download and install the application](download_executable.md) (this file will be available after creating executables) +- [Notebook usage after installation](notebook_usage.md) +- [Troubleshooting an installed app](troubleshooting_installed_app.md) + +## Customise and share (optional) + +- [Customise the installer images](installer_images.md) +- [Describe your app for the App Centre](app_manifest.md) +- [Upload external code, and publish it on PyPI (optional)](external_code_upload.md) +- [Expose tools to napari, Fiji and QuPath](tools_bridge.md) + +## Keep your app up to date (optional) + +- [Keep your app up to date](keep_app_up_to_date.md) +- [Enable automatic template updates](template_synchronization.md) + +## Notebook authoring tips + +- [Write notebooks that run in both Google Colab and JupyterLab](notebook_portability.md) +- [Hide code cells in notebooks](code_hiding.md) + +## GitHub management + +- [GitHub actions/workflows overview](workflow_status.md) +- [Troubleshooting repository setup](troubleshooting.md) +- [Create a personal access token for notebook access](personal_access_token.md) diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/app_manifest.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/app_manifest.md new file mode 100644 index 0000000..b588792 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/app_manifest.md @@ -0,0 +1,200 @@ +# Describe your app: the `labconstrictor-app.yaml` file + +`labconstrictor-app.yaml` is a small text file in the root of your repository. It says what your app is, in your own words. You write it once and keep it up to date yourself. + +Three things read it: + +- **The [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/)** builds your app's card and page from it. +- **Your release workflow** reads `platforms` to decide which installers to build. +- **Your installer** passes `hosts` and `host_requirements` to napari, Fiji and QuPath, so they know whether to list your app. + +Version numbers and download links are not in the file. They always come from your latest GitHub release. + +## Step 1: get the file + +The [repository initialiser](initialise_repository.md) asks for a one-sentence summary, the kind of app and the software it also works in. It adds the file to the initialisation pull request. Read it there and edit it if you like. + +If you skipped that section, or your repository is older than the file, create `labconstrictor-app.yaml` in the root of your repository and paste the minimal example below. The [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) also has a form that writes the file for you and checks it as you type. + +## Step 2: start with the minimal file + +These five fields are required. This file is complete and valid: + +```yaml +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +kind: analysis +distribution: + installer: true +``` + +## Step 3: add what helps people choose your app + +A fuller example. Everything after `distribution` is optional. + +```yaml +# yaml-language-server: $schema=https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json +schema: 1 +name: My App +summary: Counts nuclei in 2D fluorescence images and saves a table. +description: |- + A few paragraphs of plain text. + + Separate paragraphs with a blank line. +kind: analysis +hosts: [notebook, napari, qupath] +host_requirements: + napari: + min_version: 0.1.0-alpha.5 + why: Older plugins do not show the outlines + required: false +distribution: + installer: true + platforms: [windows-x86_64, macos-arm64, linux-x86_64] + colab: + - label: Notebook + url: https://colab.research.google.com/github/you/my-app/blob/main/notebooks/App/App.ipynb + pip: my-app +status: Available +license: MIT +authors: + - name: Ada Lovelace + orcid: 0000-0002-1825-0097 +doi: 10.1371/journal.pbio.3002740 +inputs: + - 2D TIFF images, one channel per file +outputs: + - Label masks and a CSV table +limitations: + - Not tested on 3D data +quickstart: + - Open the app and run the Welcome notebook. +categories: [nuclei, counting] +homepage: https://github.com/you/my-app +docs_url: https://github.com/you/my-app#readme +icon: app/logo/logo.png +screenshots: + - path: docs/screenshot.png + caption: The result table next to the segmented image +``` + +The first line lets editors with YAML support (for example VS Code) check the file as you type. Everything is plain text: no HTML and no Markdown. + +## The fields + +| Field | Required | What it does | Example | +|---|---|---|---| +| `schema` | Yes | The format version. Always `1`. | `1` | +| `name` | Yes | The name people know the app by (2 to 60 characters). | `My App` | +| `summary` | Yes | One sentence for the app card (20 to 200 characters). | `Counts nuclei in 2D images.` | +| `kind` | Yes | What the app is for. One of `analysis`, `segmentation`, `simulation`, `game`, `training`, `utility`. It drives the filter in the App Centre. | `analysis` | +| `distribution` | Yes | How people get the app. At least one of `installer`, `colab`, `pip`. See below. | `installer: true` | +| `hosts` | No | Where the app's tools run: `notebook`, `napari`, `fiji`, `qupath`. See below. | `[notebook, napari]` | +| `host_requirements` | No | The oldest napari, Fiji or QuPath plugin your tools need. See below. | | +| `description` | No | A few paragraphs for the app page (up to 2000 characters). | | +| `status` | No | `Experimental`, `Available` or `Deprecated`. | `Available` | +| `license` | No | The licence, as an SPDX name. | `MIT` | +| `authors` | No | A list of people: `name`, and optionally `orcid`. | `- name: Ada Lovelace` | +| `doi` | No | The DOI of the paper to cite, not of a software archive. The app page shows it as the citation. | `10.1371/journal.pbio.3002740` | +| `inputs`, `outputs`, `limitations` | No | Short lists for the app page: one to six lines of 5 to 200 characters each. | `- 2D TIFF images` | +| `quickstart` | No | Up to six short steps for a first run. | `- Open the app.` | +| `categories` | No | Up to six words a scientist would search for. | `[nuclei, counting]` | +| `homepage`, `docs_url` | No | Web addresses. They must start with `https://`. | | +| `icon` | No | A square PNG in your repository. SVG is not accepted. | `app/logo/logo.png` | +| `screenshots` | No | One to six pictures in your repository (PNG, JPG or GIF), each with a `path` and a `caption`. The caption is also the text for screen readers. | | + +The App Centre asks for a few optional fields: `status`, `quickstart`, `screenshots`, a licence, and `inputs` and `outputs` for analysis, segmentation and simulation apps. Without them your app is still listed; its page says "Not stated" or leaves that part out. + +### `distribution`: how people get the app + +| Key | What it does | +|---|---| +| `installer: true` | Your latest GitHub release carries the installers LabConstrictor builds. | +| `platforms` | The systems you support. Needs `installer: true`. Only these installers are built and offered. | +| `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | +| `pip` | The name of your package on PyPI. | + +`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. + +### `hosts`: where your tools are offered + +This field matters only if your app [exposes tools](tools_bridge.md). napari, Fiji and QuPath list your app only if you name them here. Write the hosts you have tested the app in. + +- `hosts: [notebook]` means no plugin lists the app. Its tools still work in the notebook and on the command line. +- Without a `hosts` line, every plugin lists the app. Say what you mean instead. +- Names are lower case. The check refuses a misspelt, repeated or capitalised name. + +## Plugin versions your tools need (optional) + +If your tools rely on a fix or a feature of the napari, Fiji or QuPath plugin that older plugins lack, say so with `host_requirements`. People with an older plugin keep seeing your app, with one sentence saying which plugin to update and where; your app page on the App Centre lists the versions under "Plugin versions". + +```yaml +host_requirements: + qupath: + min_version: 0.1.0-alpha.7 # a release tag of the plugin, with or without v + features: [shapes_owner_v1] # optional: a host feature id + why: Replace keeps your own annotations # optional: one line shown to the person + fiji: + min_version: 0.1.0-alpha.7 +``` + +- Name only `napari`, `fiji` or `qupath`: the notebook ships with your app and needs no plugin. +- Each needs `min_version`, `features`, or both. `required: true` makes an older plugin refuse your tools instead of warning; use it only when they really fail there. +- Write it as a block, as above. The installer passes this file to `labconstrictor-tools register`, which refuses a malformed block (a misspelt host or key, a version like `latest`); `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml` shows what it read. +- The feature ids and the rule are in [the protocol reference](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/protocol/#host-requirements-which-plugin-an-app-needs). + +## The automatic check + +The **Check App Centre manifest** workflow runs when you change the file and when you publish a release: + +- If the file is missing, it shows a warning and passes. +- If the file is invalid, it fails and says what to fix. This never stops your installers from being built. +- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](keep_app_up_to_date.md). +- It also checks that the icon and screenshots you name exist in the repository. + +## Check it yourself + +To check the file before you push: + +1. **On your computer.** From the root of your repository: + + ```bash + pip install pyyaml jsonschema + python .tools/python/check_app_manifest.py + ``` + +2. **In your browser.** Paste your values into the form on the [Submit page](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). It checks them against the same schema. + +If your app exposes tools, also run `labconstrictor-tools check --module _lc_tools --app-manifest labconstrictor-app.yaml`. It prints the `hosts` and `host_requirements` it read, which is what the installer will register. + +The rules themselves are in the [schema](https://cellmigrationlab.github.io/LabConstrictor-Site/schema/labconstrictor-app.schema.json). Your repository has a copy in `.tools/schema/`, and the check uses that copy. + +## Common mistakes + +| What the check says, or what you see | Fix | +|---|---| +| A field "is not allowed" or is "unexpected" | The name is misspelt, or it is at the wrong level. For example `platforms` belongs under `distribution`. | +| `summary` is too short or too long | Write one sentence of 20 to 200 characters. | +| `platforms` without `installer` | Add `installer: true`. `platforms` only applies to installers. | +| The icon or a screenshot is "not found" | The path starts at the root of your repository, with no leading `/`. The file must be committed. | +| A Colab link is refused | The address must start with `https://colab.research.google.com/`. | +| `min_version: 0.2` is refused | YAML reads `0.2` as a number. Put it in quotes: `"0.2"`. | +| Your app is missing from napari, Fiji or QuPath | The host is not in `hosts`, or the app was installed before you added it. Publish a release and install it again. | +| The check passes but nothing changes in the App Centre | The App Centre reads the file from your default branch and updates once a day. | +| Text shows `**stars**` or tags | The fields are plain text. Remove Markdown and HTML. | + +## Get listed + +Having the file does not list your app by itself. To list it, [submit your repository](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/) to the App Centre. You do this once: later releases appear by themselves. + +--- + +
+ +[← Previous](installer_images.md)            +[🏠 Home](README.md)            +[Next β†’](external_code_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/before_getting_started.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/before_getting_started.md new file mode 100644 index 0000000..fd974a6 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/before_getting_started.md @@ -0,0 +1,52 @@ +# 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 for Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`) with [conda constructor](https://github.com/conda/constructor). + +### 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. +- **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_37_to_v0_1_38/previous/.tools/docs/create_repository.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/create_repository.md new file mode 100644 index 0000000..e2db347 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/create_repository.md @@ -0,0 +1,33 @@ +# Create your repository + +Your app lives in its own GitHub repository, made from the LabConstrictor template. + +1. Open the [LabConstrictor template on GitHub](https://github.com/CellMigrationLab/LabConstrictor). +2. Click the green **Use this template** button at the top right, then **Create a new repository**. + + ![Use template screenshot](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Use_Template.png) + +3. Fill in the details: + - **Include all branches:** leave it off. + - **Owner:** your personal account or your research group's organization. + - **Repository name:** a short name, for example `MyLabTools`. We recommend using it as your app's name when you initialise the repository. + - **Description** (optional): what your notebooks do, for example "Automated cell migration analysis". + - **Visibility:** **Public** to share your installers right away; **Private** to keep the code within your lab while you work on it. A private repository cannot be listed in the App Centre: make it public before you submit your app. +4. Click **Create repository**. + +Next: [Initialise your repository](initialise_repository.md). + +## Template updates (optional, later) + +The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](keep_app_up_to_date.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. + +--- + +
+ +[← Previous](before_getting_started.md)            +[🏠 Home](README.md)            +[Next β†’](initialise_repository.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/executable_creation.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/executable_creation.md new file mode 100644 index 0000000..b90ce74 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/executable_creation.md @@ -0,0 +1,55 @@ +# Create installer files + +Publishing a GitHub release builds the installers of your app for Windows (`.exe`), macOS (`.pkg`, Apple Silicon and Intel) and Linux (`.sh`) and attaches them to the release. + +## What you need + +- At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md). +- A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`). + +## Please check before proceeding + +Open the **Actions** tab of your repository and check that no workflow is running. If one is in progress, wait until it finishes: a release started while another workflow runs may build from files that are about to change. + +## 1. Draft a new release + +1. Go to your repository's main page. +2. Click **Releases** (in the right sidebar). +3. Click **Create a new release** and fill in: + - **Tag**: click **Create a new tag** and enter the version number, for example `0.0.1`. It must have the form `MAJOR.MINOR.PATCH` (`1.0.0`, `1.2.3`). A `v` in front (`v1.0.0`) also works: the installers are named with the version without it. + - **Release title**: for example `Initial release`. + - **Description** (optional): what is new in this release. + +## 2. Publish the release + +Click **Publish release**. This starts the workflow **Build Release Installers**. It sets the version in your repository's files, then builds one installer per system. + +## Check that it worked + +- In the **Actions** tab, the run of **Build Release Installers** has a green tick ([how to read a run](workflow_status.md)). +- Open your repository's **Releases** page and the release you published: its **Assets** list holds the installers, named `--` (for example `MyApp-0.0.1-Windows-x86_64.exe`). +- `.tools/docs/download_executable.md` in your repository now has download buttons for this release. + +## If something does not work + +- **The run stops at "check_placeholders.py", "Installers to build" or with conflicting package versions.** See [Troubleshooting repository setup](troubleshooting.md): each of these has its own section. +- **Another step failed.** Open the failed run and read the log of the red step ([how](workflow_status.md)). After you fix the problem, delete the release and its tag, then publish the release again. +- **An installer is missing for one system.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml` (all of them when it is not set): see [Describe your app for the App Centre](app_manifest.md). + +## 3. After the release + +- Try your installer yourself: [Install an app](install.md), then [Use notebooks after installation](notebook_usage.md). +- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md). +- Receive future template improvements as pull requests: [Keep your app up to date](keep_app_up_to_date.md). + + +--- + +
+ +[← Previous](notebook_upload.md)            +[🏠 Home](README.md)            +[Next β†’](installer_images.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/external_code_upload.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/external_code_upload.md new file mode 100644 index 0000000..c19858c --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/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 β†’](keep_app_up_to_date.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/install.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/install.md new file mode 100644 index 0000000..d0c84d5 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/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: [Use notebooks after installation](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: [Use notebooks after installation](notebook_usage.md). diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/keep_app_up_to_date.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/keep_app_up_to_date.md new file mode 100644 index 0000000..5831bee --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/keep_app_up_to_date.md @@ -0,0 +1,32 @@ +# Keep your app up to date + +The LabConstrictor template keeps improving. Your repository can receive those improvements, including updates to its GitHub Actions workflows, as a pull request that you review and merge. This is optional and can wait until after your first release. + +## How it works + +The **Sync with Template Repository** workflow runs every Monday at 09:00 UTC, and you can also start it yourself from the **Actions** tab. When the template has a newer version than your repository, the workflow applies the changes needed to move your repository to that version and opens a pull request titled "Sync template to version" followed by the new version number. You then merge it as described in [Accept a pull request](accept_pull_request.md). When your repository is already on the latest template version, the run ends without opening a pull request. + +Template-managed files, such as the copy of the App Centre manifest schema used by the **Check App Centre manifest** workflow, are refreshed by the same pull request. If that check rejects a field the App Centre accepts, your copy of the schema is older than the App Centre: merge the latest sync pull request. + +## What you lose without the setup + +Opening that pull request needs a token that you create and save in your repository as the secret `LABCONSTRICTOR_SYNC_TOKEN`. Without it, the workflow stops with the error "Synchronization setup required" as soon as a newer template version exists. No update pull request is created, so your repository stays on the template version it has. + +## Set it up + +Follow [Enable automatic LabConstrictor template updates](template_synchronization.md): create the token, save it as the secret, and renew it when it expires ([Renewing an expired token](template_synchronization.md#renewing-an-expired-token)). + +## If it does not work + +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions), and [Check the status of GitHub workflows](workflow_status.md) for how to read a failed run. + +--- + +
+ +[← Previous](external_code_upload.md)            +[🏠 Home](README.md)            +[Next β†’](template_synchronization.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_requirements.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_requirements.md new file mode 100644 index 0000000..c686776 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_requirements.md @@ -0,0 +1,115 @@ +# Generate the requirements of your notebook + +Every notebook you upload needs a `requirements.yaml` file: the Python version and the packages it uses, each with its exact version. The installer installs these packages on your users' computers. + +There are two ways to make the file: + +* **Option 1 (automated):** the Requirements Generator notebook reads the packages from the Python environment where your notebook runs. Use it when you start from scratch. +* **Option 2 (manual):** you write the file yourself and check it with the Requirements Validator notebook. Faster if you already have a `requirements.txt` with versions. + +## What you need + +- Your notebook, running without errors in a Python environment: on your computer (conda or virtualenv) or in Google Colab. +- For Option 1 on your computer: that same environment, with Jupyter. The generator must run in the environment your notebook uses, because it reads the package versions from it. + +## Option 1: Automated extraction of requirements + +### 1. Open the Requirements Generator notebook + +Open it where your notebook runs: + +* **On your computer:** download [Requirements_Generator.ipynb](../notebooks/Requirements_Generator.ipynb) (with the download button shown below) and open it in the environment you use for your notebook. If you have several conda environments, use the one your notebook runs in. + + ![Download Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Download_Notebook.png) + +* **Google Colab:** open the [Requirements Generator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Generator.ipynb). Colab runs each notebook in its own session, so the packages your notebook installs must be installed in the generator's session too: the generator finds your notebook's `pip install` commands and offers a cell that runs them. + +### 2. Run the Requirements Generator + +Run its cells in order and follow the instructions in the notebook: choose your notebook, add helper files your notebook uses if any, then generate the file. It saves `_requirements.yaml` next to the generator (in Colab it is also downloaded). You can upload it with that name: the upload form saves it as `requirements.yaml`. + +## Option 2: Manual extraction of requirements + +### 1. Create a `requirements.yaml` file + +Start from the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). It has three fields: + +* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). The upload form refuses ranges such as `pandas>=2`. +* **`python_version`:** the Python version the notebook runs with (for example `3.11.1`). All notebooks of an app must use the same one. +* **`description`:** one sentence on what the notebook does. + +```yaml +dependencies: + - pandas==2.2.2 + - ipython==7.34.0 + - tqdm==4.67.1 +description: This notebook is for analyzing cell migration data... +python_version: 3.11.1 +``` + +### 2. Check it with the Requirements Validator notebook + +* **Google Colab (recommended, nothing to install):** open the [Requirements Validator in Colab](https://colab.research.google.com/github/CellMigrationLab/LabConstrictor/blob/main/.tools/notebooks/Requirements_Validator.ipynb). +* **On your computer:** download [Requirements_Validator.ipynb](https://raw.githubusercontent.com/CellMigrationLab/LabConstrictor/main/.tools/notebooks/Requirements_Validator.ipynb) and open it in any Python environment that has `ipywidgets`. + +Follow the instructions in the notebook and give it your `requirements.yaml` when it asks. + +## Check that it worked + +- You have a `requirements.yaml` (or `_requirements.yaml`) file. +- Every line under `dependencies` has the form `package==version`, and `python_version` is the version your notebook runs with. + +You are ready to [upload your notebook](notebook_upload.md). + +## If something does not work + +- **A package is missing from the generated file.** The generator finds only packages installed in the environment it runs in. Open it in the environment of your notebook, or add the package by hand with its version. +- **The upload form says "Dependency '...' is not in the correct format".** Fix that line to `package==version`. +- **The workflow stops after the upload with conflicting versions.** Two notebooks ask for different versions of a package: see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package). + +## What happens after you upload: the lock file + +When a notebook and its `requirements.yaml` reach the repository, the workflow **Updates on notebook change** merges the requirements of every notebook into `requirements.txt`, plus `requirements_gpu.txt` and, if a notebook needs them, `requirements-windows.txt`, `requirements-linux.txt` or `requirements-macos.txt`. + +The installer uses `requirements_gpu.txt` when it finds an NVIDIA GPU on Windows or Linux. In that file `tensorflow` becomes `tensorflow[and-cuda]` on Linux only: TensorFlow has had no Windows GPU build since version 2.10, and its CUDA packages exist only for Linux, so Windows keeps plain `tensorflow` (CPU). + +The workflow then writes a **lock file** next to each requirements file (`requirements.lock.txt`, ...). A lock file lists every package the installer installs, including the packages your packages depend on, each with its exact version, for Windows, macOS and Linux. The installer installs the lock file, so every installation of a release gets the same versions. + +* A lock file changes only when its requirements file, the Python version or the JupyterLab version changes. Pushing a notebook without new requirements does not move any version. +* To move every package to its newest version, delete the `requirements*.lock.txt` files and run the workflow by hand (**Actions > Updates on notebook change > Run workflow**). +* If the requirements cannot be locked, the workflow shows a warning and the installer installs the plain `requirements.txt` instead. + +### When notebooks ask for different versions of a package + +The merge never changes a notebook's requirement silently. Requirements are kept as written (`numpy>=1.24` stays `numpy>=1.24`), and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: + +* two notebooks pin a package to different versions (`numpy==1.26.4` and `numpy==2.0.0`); +* a pin does not meet another notebook's requirement (`numpy==2.0.0` and `numpy<2`); +* no version meets all the requirements (`numpy<2` and `numpy>=2.1`). + +The log of the **Run merge script** step names the package, every notebook and its requirement. Then either: + +* **make the notebooks agree:** change their `requirements.yaml` to a version that works for every notebook; or +* **decide explicitly** in `requirements_overrides.yaml`, at the top of the repository, which requirement every notebook gets, and why: + +```yaml +overrides: + numpy: + use: "==2.0.0" + reason: "Notebook A was re-run with numpy 2.0.0 and gives the same results; notebook B needs 2.0." +``` + +The decision and its reason are written at the top of the generated requirements files. Pushing `requirements_overrides.yaml` runs the workflow again. A release also stops while a conflict is not resolved. + +Requirements with different platform markers (`; sys_platform == "win32"`) are kept as separate lines, and `NumPy`, `numpy` and `num_py` count as the same package, as for pip. + +--- + +
+ +[← Previous](accept_pull_request.md)            +[🏠 Home](README.md)            +[Next β†’](notebook_upload.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_upload.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_upload.md new file mode 100644 index 0000000..e0fc1c7 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_upload.md @@ -0,0 +1,193 @@ +# Add or update a notebook + +Upload a notebook and its `requirements.yaml` to your repository with the LabConstrictor web form. The form opens a pull request; when you merge it, GitHub checks that the notebook's packages can be installed together. + +## What you need + +- An initialised repository: see [Initialise your repository](initialise_repository.md). +- Your notebook (`.ipynb`) and its requirements file: see [Generate the requirements of your notebook](notebook_requirements.md). +- A GitHub personal access token (classic, it starts with `ghp_`): see [Generate a GitHub personal access token](personal_access_token.md). + +## 1. Prepare your notebook + +The first cell of every notebook checks its version, so users see when a newer version exists. + +1. Add a code cell at the top of your notebook (see this [JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md) if you need help), and paste the code below into it. +2. Set `current_version` to the version of your notebook (for example `"0.0.2"`) and `notebook_name` to the name of the notebook file without `.ipynb`. + +> Each time you change what the notebook does, increase `current_version` so users can see there is a new version. + +```python +# @markdown Run this cell to check this notebook's version. + +current_version = "0.0.1" +notebook_name = "Notebook_template" # Replace with the actual notebook name + +# First of all check if ipywidgets is installed, if not through an informative error +try: + import ipywidgets as widgets +except ImportError: + raise ImportError("ipywidgets is not installed. Please install it using 'pip install ipywidgets' or 'conda install -c conda-forge ipywidgets'.") + +from IPython.display import display + +try: + from google.colab import output + output.enable_custom_widget_manager() + + try: + import yaml + except ImportError: + raise ImportError("pyyaml is not installed. Please install it using 'pip install pyyaml' or 'conda install -c conda-forge pyyaml'.") + + import requests + import base64 + + # Create widgets + github_repo = widgets.Text( + value="", + description="*GitHub Repository URL:", + placeholder="e.g https://github.com/username/repository", + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + github_token = widgets.Password( + value="", + description="*Personal Access Token:", + placeholder="[Disabled] e.g. ghp_XXXXXXXXXXXXXXXXXXXX", + disabled=True, + layout=widgets.Layout(width="70%"), + style={'description_width': '150px'}, + ) + + test_button = widgets.Button( + description="Test Connection", + button_style='success', + ) + + output_area = widgets.HTML() + + # By default the repository is considered public + if "repository_is_private" not in globals(): + repository_is_private = False + elif repository_is_private: + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + + def on_test_button_clicked(b): + global repository_is_private + + # Check that the GitHub repository URL is provided + if not github_repo.value: + output_area.value = "⚠️ Please provide a GitHub repository URL." + return + + # Get the owner and repo name from the URL + repo_url = github_repo.value.rstrip('/') + github_owner, github_repo_name = repo_url.split('/')[-2:] + + # Online version checking file path + version_file_path = "notebooks/notebook_latest_versions.yaml" + version_url = f"https://api.github.com/repos/{github_owner}/{github_repo_name}/contents/{version_file_path}" + + # Do an initial request to check if the repository is public + if not repository_is_private: + version_response = requests.get(version_url) + if version_response.status_code == 404: + repository_is_private = True + github_token.disabled = False + github_token.placeholder = "e.g. ghp_XXXXXXXXXXXXXXXXXXXX" + output_area.value = f"⚠️ We have detected that the repository might be private. Please provide a Personal Access Token and click 'Test Connection' again." + return + else: + headers = {"Accept": "application/vnd.github.v3+json"} + if not github_token.value: + output_area.value = "⚠️ Personal Access Token is required for private repositories." + return + headers["Authorization"] = f"token {github_token.value}" + + version_response = requests.get(version_url, headers=headers) + + # Check the response status + if version_response.status_code == 200: + content = version_response.json()['content'] + decoded_content = base64.b64decode(content).decode('utf-8') + config = yaml.safe_load(decoded_content) + # notebook_latest_versions.yaml groups the notebooks by folder: {"": {"": ""}} + latest_version = next((str(group[notebook_name]) for group in (config or {}).values() + if isinstance(group, dict) and notebook_name in group), "") + + output_area.value = (f"Notebook version: `{current_version}`
" + f"Latest version available: `{latest_version}`
") + + if latest_version == "": + output_area.value += "⚠️ This notebook is not listed in the version file.
" + elif current_version == latest_version: + output_area.value += "βœ… This notebook is up-to-date.
" + else: + output_area.value += f"⚠️ A new version of this notebook is available." + else: + output_area.value += "⚠️ Could not retrieve the version file.
" + + test_button.on_click(on_test_button_clicked) + # Widget layout + widget_box = widgets.VBox([github_repo, github_token, test_button, output_area]) + display(widget_box) +except ImportError: + display(widgets.HTML('To check the notebook version, please go to the Welcome notebook.')) +``` + + +## 2. Generate the requirements file + +Create the `requirements.yaml` file of your notebook: see [Generate the requirements of your notebook](notebook_requirements.md). + +## 3. Upload to the repository + +1. Open the [LabConstrictor form](https://labconstrictor-form.streamlit.app/). If it shows a `Zzzz` message, click `Yes, get this app back up!` and wait. +2. Click **Upload/Update notebook**. +3. Upload your notebook file (`.ipynb`) and its requirements file. +4. Click **βž• Validate & Add Submission**. If the notebook and its requirements pass the checks, the notebook appears in the **πŸ“ƒ Submission list**. Repeat steps 3 and 4 to add more notebooks to the same pull request. +5. Under **⬆️ Upload it to GitHub**, enter your repository's address and your personal access token. +6. Click **πŸš€ Create pull request**. + +## 4. Merge the pull request + +The form opens a pull request titled "Upload/Update notebook" followed by the notebook's name. Merge it: see [Accept a pull request](accept_pull_request.md). The merge starts the workflow **Updates on notebook change**, which merges the requirements of all notebooks, hides the code cells (unless you disabled it) and checks that the packages can be installed. + +## Check that it worked + +- In the **Actions** tab, the run of **Updates on notebook change** has a green tick ([how to read a run](workflow_status.md)). +- Your notebook is in `notebooks//`, next to its `requirements.yaml`. +- `notebooks/notebook_latest_versions.yaml` lists the notebook with its `current_version`. + +You can now [create the installers](executable_creation.md). + +## If something does not work + +- **The form refuses the requirements file.** The message names the line to fix. Each dependency must be `package==version`: see [Generate the requirements of your notebook](notebook_requirements.md). +- **The workflow failed and your merge was undone.** When the merged requirements cannot be installed, the workflow reverts your merge automatically. Open the failed run, find the package that failed in the log, fix the notebook's requirements and upload again. +- **The workflow stops with conflicting versions.** Notebooks ask for different versions of the same package; nothing is installed and the requirements files are not changed. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). +- **The version check says "This notebook is not listed in the version file".** `notebook_name` in the first cell does not match the notebook's file name. + +--- + +## How to update an existing notebook + +Updating a notebook works the same way as adding one: + +1. In the first cell of your notebook, increase `current_version` (for example from `1.0.0` to `1.0.1`). +2. If the notebook now uses other packages or versions, generate its requirements file again. +3. Upload the notebook and its requirements file with the [LabConstrictor form](https://labconstrictor-form.streamlit.app/), as above. Keep the notebook's file name exactly the same: a notebook with the same name replaces the old one. + +--- + +
+ +[← Previous](notebook_requirements.md)            +[🏠 Home](README.md)            +[Next β†’](executable_creation.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_usage.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_usage.md new file mode 100644 index 0000000..209dce7 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/notebook_usage.md @@ -0,0 +1,51 @@ +# Use notebooks after installation + +How to open an installed app, run its notebooks and update them. + +## Open the app + +To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. + +A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the Welcome notebook: + +![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) + +## Open a notebook + +Run the cell of the Welcome notebook. It shows a table of the app's notebooks, with their version and whether a newer version exists. Click **Open the notebook** in the last column to open a notebook in a new tab. + +If the app's repository on GitHub is private, the Welcome notebook asks for a GitHub personal access token to check for new versions: see [Generate a GitHub personal access token](personal_access_token.md). + +## Run a notebook + +Notebooks made with LabConstrictor can hide their code. Run each cell with its play button, or select the cell and click the play button in the top toolbar. The **Show/Hide Code** button in the toolbar shows the code. See [Hide code cells in notebooks](code_hiding.md) for pictures. If you are new to JupyterLab, see [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). + +## Update a notebook + +When a newer version of a notebook is published, the Welcome notebook shows **Update** next to it. + +1. Close the notebook's tab first. Otherwise JupyterLab can save the old copy over the new one. +2. Click **Update**, then confirm with **Back up and update**. + +Your current copy, with your changes and outputs, is kept as `.backup-.ipynb` in the same folder. If the download fails, your notebook is not changed. + +## Close the app + +Keep the terminal window open until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. + +## If something does not work + +See [Troubleshooting an installed app](troubleshooting_installed_app.md). + + +--- + + +
+ +[← Previous](download_executable.md)            +[🏠 Home](README.md)            +Next β†’ + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/personal_access_token.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/personal_access_token.md new file mode 100644 index 0000000..b0632c7 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/personal_access_token.md @@ -0,0 +1,39 @@ +# Generate a GitHub personal access token + +> Looking for the token used by the automatic template update workflow? Follow the dedicated [automatic template synchronization guide](template_synchronization.md). It uses a repository-scoped fine-grained token with a different purpose and secret name. + +If you want to work with GitHub repositories from your notebook, like cloning, editing, or pushing files, you’ll need a GitHub Personal Access Token (PAT). This token lets you authenticate your API calls and gives you the right permissions. The GIF below shows the steps to create a token. + +![Gif of generating a GitHub token](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/GitHub_Access_Token.gif) + +> The LabConstrictor repository form accepts only a classic token, which starts with `ghp_`. A fine-grained token (it starts with `github_pat_`) is rejected. + +To see the full steps, follow the instructions below. + +## Create the token + +1. Go to https://github.com/ and sign in. +2. Click your profile icon (top right) βž” **Settings** +3. In the left sidebar, select **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)** +4. On the top right side (at the same level as `Personal access tokens (classic)`), click on **Generate new token** βž” **Generate new token (classic)** +5. Give your token a descriptive **Name** (e.g., `Notebook RW Token`) and set an **Expiration** if desired +6. Under **Scopes**, tick **repo** + - *(Optional: To only work with public repositories, select **public_repo** instead of **repo**)* +7. Click **Generate token** at the bottom +8. **Copy** your new token right away. You won’t be able to see it again later! +9. Paste the token into your notebook’s `GitHub-token` field, so API calls authenticate as the chosen owner. + +A classic token with the **repo** scope can read and write your repositories, so keep it private. + + +--- + + +
+ +[← Previous](troubleshooting.md)            +[🏠 Home](README.md)            +Next β†’ + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/template_synchronization.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/template_synchronization.md new file mode 100644 index 0000000..d9c0d42 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/template_synchronization.md @@ -0,0 +1,86 @@ +# Enable automatic LabConstrictor template updates + +The **Sync with Template Repository** workflow checks the LabConstrictor template every week. When a newer template version exists, it opens a pull request in your repository with the changes, for you to review and merge. + +To open that pull request, the workflow needs a token that you create once and save in your repository. The token gives access only to the repository you select, not to your other repositories. + +## What you need + +- Admin access to your app's repository on GitHub (to add a secret). + +## Step 1: Create the synchronization token + +![GIF showing the token creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Token_Creation.gif) + +Open [this link](https://github.com/settings/personal-access-tokens/new?name=LabConstrictor+Sync&description=Allows+LabConstrictor+to+prepare+template+update+pull+requests.&expires_in=365&contents=write&pull_requests=write&workflows=write), which fills in most of the form, then: + +1. Under **Resource owner**, select the owner of your repository. +2. Under **Repository access**, select **Only select repositories**, then select your repository. +3. Choose an expiration period. The link suggests 365 days. +4. Check these repository permissions: + - **Contents:** Read and write + - **Pull requests:** Read and write + - **Workflows:** Read and write +5. Select **Generate token**. +6. Copy the token. + +> GitHub shows the token only once. Keep the page open until you have saved it in Step 2. + +## Step 2: Save the token as a repository secret + +![GIF showing the secret creation](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Synchronisation_Secret_Creation.gif) + +1. Open your repository. +2. Select **Settings**. +3. In the left sidebar, select **Secrets and variables**, then **Actions**. +4. Select **New repository secret**. +5. Enter this exact name: + + ```text + LABCONSTRICTOR_SYNC_TOKEN + ``` + +6. Paste the token into the **Secret** field. +7. Select **Add secret**. + +GitHub encrypts repository secrets: the token is not shown in the repository or in the workflow logs. + +## Check that it worked + +Open the **Actions** tab, select **Sync with Template Repository** and click **Run workflow**. The run ends with a green tick. If a newer template version exists, a pull request titled "Sync template to version ..." appears in the **Pull requests** tab: merge it as described in [Accept a pull request](accept_pull_request.md). + +## Repositories created before template version 0.1.12 + +The older synchronization workflow does not use `LABCONSTRICTOR_SYNC_TOKEN`. If a run failed with an error saying that a GitHub App cannot create or update a workflow without `workflows` permission, edit the workflow once: + +1. Open [`.github/workflows/sync_template.yml`](../../.github/workflows/sync_template.yml) in your repository. +2. Select the pencil icon to edit the file. +3. Replace all its lines with those of the [template's workflow](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.github/workflows/sync_template.yml). +4. Select **Commit changes** and commit directly to the default branch. +5. Run **Sync with Template Repository** again. + +The next template update then keeps the workflow up to date by itself. + +## Renewing an expired token + +When the token expires, runs fail with an authentication error such as "Bad credentials". Then: + +1. Create a new token as in Step 1. +2. Open **Settings β†’ Secrets and variables β†’ Actions**. +3. Select `LABCONSTRICTOR_SYNC_TOKEN`. +4. Select **Update secret** and paste the new token. +5. Run **Sync with Template Repository** again. + +## If something does not work + +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions). + +--- + +
+ +[← Previous](keep_app_up_to_date.md)            +[🏠 Home](README.md)            +[Next β†’](notebook_portability.md) + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/tools_bridge.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/tools_bridge.md new file mode 100644 index 0000000..f96331e --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/tools_bridge.md @@ -0,0 +1,78 @@ +# Expose your app's tools to napari, Fiji and QuPath (optional) + +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_37_to_v0_1_38/previous/.tools/docs/troubleshooting.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/troubleshooting.md new file mode 100644 index 0000000..5f68a97 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/troubleshooting.md @@ -0,0 +1,75 @@ +# Troubleshooting repository setup + +Problems with your repository on GitHub. For problems with an installed app on your computer, see [Troubleshooting an installed app](troubleshooting_installed_app.md). + +## Synchronisation is failing on GitHub Actions + +The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Enable automatic LabConstrictor template updates](template_synchronization.md). + +### "Synchronization setup required": the token is missing + +Create the token and save it under **Settings β†’ Secrets and variables β†’ Actions** with this exact name: + +```text +LABCONSTRICTOR_SYNC_TOKEN +``` + +### GitHub refuses to update a workflow file + +If the error says GitHub refuses to create or update a workflow without `workflows` permission, check that the token has all of these repository permissions: + +- **Contents:** Read and write +- **Pull requests:** Read and write +- **Workflows:** Read and write + +Repositories created before template version `0.1.12` also need the one-time workflow edit described in the synchronization guide, so that the workflow uses the secret. + +### Bad credentials or authentication failed + +The token has expired or was revoked. Create a new token and update the `LABCONSTRICTOR_SYNC_TOKEN` secret: see [Renewing an expired token](template_synchronization.md#renewing-an-expired-token). + +## The release stops at "check_placeholders.py" + +Before it builds the installers, the release workflow checks that no template placeholder (`PROJECT_NAME`, `PYTHON_PROJ_NAME`, `UNDERSCORED_PROJECT_NAME`, ...) is left in a file the installer ships. An installer with one would fail on your users' computers (for example `No module named 'PYTHON_PROJ_NAME'` at the end of the installation). + +The log of the failed step lists each file and line. Replace the placeholder there with your app's value: `PYTHON_PROJ_NAME` is the Python package of the app (usually its folder in `src/`), `PROJECT_NAME` the app name. For `app/menuinst/Welcome.ipynb`, edit `.tools/templates/Welcome_template.ipynb` instead: the Welcome notebook is made from it at every release. Commit, then publish the release again. + +## The release stops at "Installers to build" + +The release reads `distribution.platforms` in `labconstrictor-app.yaml` to decide which installers to build. It stops when the file is not valid YAML, when `platforms` is not a list, or when it lists none of the systems the release can build: `windows-x86_64`, `linux-x86_64`, `macos-arm64` and `macos-x86_64`. The log of the step says which. Fix `labconstrictor-app.yaml` (see [Describe your app for the App Centre](app_manifest.md)), commit, then publish the release again. + +## "The notebooks ask for incompatible package versions" + +The **Run merge script** step of **Updates on notebook change**, or the `merge_requirements.py --check` step of a release, stops when notebooks pin a package to different versions, or ask for versions that no single version meets. Its log lists the package, each notebook and its requirement. Make the notebooks agree, or decide in `requirements_overrides.yaml` which requirement every notebook gets and why, then push it: the workflow runs again. See [When notebooks ask for different versions of a package](notebook_requirements.md#when-notebooks-ask-for-different-versions-of-a-package). + +If a template update created `requirements_overrides.yaml` for you, its entries keep the versions your app installed until then (the newest of the pins). Check each one with every notebook that uses the package, and replace its reason with yours. + +## Publishing to PyPI fails + +The workflow **Publish the Python package to PyPI** (`publish_pypi.yml`) runs at a release only when the repository variable `PYPI_PUBLISH` is `true` or `testpypi` (see [Upload external code](external_code_upload.md#4-publish-the-code-on-pypi-optional)). Its first job checks and builds the package; its second job uploads it. The installers do not depend on it: a failure here leaves the release and its installers as they are. + +| What you see | What to do | +|---|---| +| Both jobs are grey (skipped) | The variable is missing or has another value. It must be a **variable** (Settings > Secrets and variables > Actions > **Variables**), not a secret, named `PYPI_PUBLISH`, with the value `true` or `testpypi` exactly. | +| `invalid-publisher: valid token, but no corresponding publisher` | The trusted publisher on pypi.org (or test.pypi.org for `testpypi`) does not match this workflow. Check the five fields: owner, repository, workflow `publish_pypi.yml`, environment `pypi`, and the project name. Then re-run the failed job (Actions > the run > **Re-run failed jobs**). | +| `... isn't allowed to upload to project ...` (403) | The name belongs to another PyPI project that this repository is not a publisher of. If it is yours, add the publisher in that project's **Publishing** page; if not, choose another `name=` in `setup.py` (and `distribution.pip`). | +| `PyPI already has ` (or `File already exists`) | That version was uploaded before; a version can be uploaded only once, even after it was deleted. Publish a new release with a higher version. | +| `There is no Python package in src/` | Add your code as a folder with an `__init__.py` in `src/` (see [Upload external code](external_code_upload.md)), or delete the variable `PYPI_PUBLISH`. | +| `... also publishes to PyPI` | Another workflow of the repository uploads to PyPI too. Keep one: delete the variable `PYPI_PUBLISH`, or delete the other workflow. | +| `distribution.pip of labconstrictor-app.yaml is ..., but setup.py names the package ...` | Make the two names the same. | +| `PyPI refuses a package whose dependency is a URL` | `setup.py` lists a dependency as `name @ git+https://...`. Publish that dependency on PyPI and name it with a version, or move the URL to `requirements.txt` (the installer still installs it; the PyPI package leaves it out). | +| `setup.py still has the template placeholder ...` | Replace the placeholder in `setup.py` (the log says which), commit, and publish a new release. | +| The upload job waits | The `pypi` environment has required reviewers (Settings > Environments > pypi): one of them approves the upload in the run. | + +After a fix, re-run the failed jobs of the run if nothing in the repository changed (a publisher fixed on pypi.org); otherwise publish a new release. + +--- + +
+ +[← Previous](workflow_status.md)            +[🏠 Home](README.md)            +[Next β†’](personal_access_token.md) + + +
diff --git a/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/troubleshooting_installed_app.md b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/troubleshooting_installed_app.md new file mode 100644 index 0000000..76cf272 --- /dev/null +++ b/.template_sync/resources/v0_1_37_to_v0_1_38/previous/.tools/docs/troubleshooting_installed_app.md @@ -0,0 +1,69 @@ +# Troubleshooting an installed app + +Problems with an app on your computer, after you installed it. For problems with your repository on GitHub, see [Troubleshooting repository setup](troubleshooting.md). + +## Where to find the logs + +Two files in the app's install folder (the folder you chose when you installed it) record what happened: + +- `menuinst_debug.log`: what the installer did. +- `launcher_debug.log`: what happened when you opened the app. If the app cannot start, a message names this file. + +Send them along when you ask the app's developer for help. + +## App still appears in the Windows Installed apps list after uninstalling + +On Windows, after you uninstall the app from `Settings > Apps > Installed apps` as explained in [Uninstall an app](install.md#uninstall-an-app), the app can stay in the list and refuse to uninstall again, with a message like this: + +![Uninstall error message](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/troubleshooting/Not_Uninstall.png) + +Uninstall it from the Control Panel instead: + +1. Open the Control Panel. You can search for it in the Windows search bar. +2. Go to `Programs > Programs and Features`. +3. Find the app in the list, right-click it, and select `Uninstall`. +4. A message may say something like "An error occurred while trying to uninstall xxx. It might have already been uninstalled." Click `Yes`. + +The app is then removed from the list. + +## Windows asks for administrator rights for python.exe while uninstalling + +Uninstalling an app made with template 0.1.20 or earlier may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. + +1. Click **No**. The prompt is not needed. +2. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. + +The uninstall then finishes normally, and nothing outside the app folder is changed. **Yes** and **Retry** do not help: the same error comes back. + +Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. + +Installers built with template 0.1.21 or later do not have this problem ([details](migration_0_1_21.md)). + +## The notebook fails with "No module named ..." although the installation finished + +The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This happens with apps made with template 0.1.23 or earlier when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. + +Install a release made with template 0.1.24 or later: it always uses the app's own Python. Until then, you can delete the personal kernel folder, but the other Jupyter installations on the computer that use it lose it too: + +- Linux: `~/.local/share/jupyter/kernels/python3` +- macOS: `~/Library/Jupyter/kernels/python3` +- Windows: `%APPDATA%\jupyter\kernels\python3` + +## My changes to a notebook are gone after an update + +The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without keeping a copy. + +## JupyterLab does not start because Windows reports an ASN.1 certificate error + +A broken certificate in the Windows certificate store can stop JupyterLab from starting. The app's launcher works around it: it first uses the system's certificates and, if one of them cannot be read, falls back to a verified certificate bundle. Certificate checks are never switched off. `launcher_debug.log` says which one was used. + +If your organisation uses its own certificate authority, save its certificates as a PEM file and set one of these environment variables to the path of that file before you install or open the app: + +- `LABCONSTRICTOR_CA_BUNDLE`, for every LabConstrictor app; +- `_CA_BUNDLE`, for one app: the app's name in capitals, with spaces and punctuation replaced by `_` (for the app "My Project", `MY_PROJECT_CA_BUNDLE`). + +To test the launcher without opening JupyterLab, run this in a command prompt (replace `` and ``): + +```text +\python.exe \\launch_jupyter.py --self-test +``` diff --git a/.tools/docs/README.md b/.tools/docs/README.md index 31305e1..82e0fc5 100644 --- a/.tools/docs/README.md +++ b/.tools/docs/README.md @@ -13,7 +13,7 @@ This file temporarily lists all internal LabConstrictor documentation. After you - [Create executable installers](executable_creation.md) - [Install an app](install.md) - [Download and install the application](download_executable.md) (this file will be available after creating executables) -- [Notebook usage after installation](notebook_usage.md) +- [Open and use an app](notebook_usage.md) - [Troubleshooting an installed app](troubleshooting_installed_app.md) ## Customise and share (optional) @@ -25,8 +25,7 @@ This file temporarily lists all internal LabConstrictor documentation. After you ## Keep your app up to date (optional) -- [Keep your app up to date](keep_app_up_to_date.md) -- [Enable automatic template updates](template_synchronization.md) +- [Keep your app up to date](template_synchronization.md) ## Notebook authoring tips diff --git a/.tools/docs/app_manifest.md b/.tools/docs/app_manifest.md index b588792..677c911 100644 --- a/.tools/docs/app_manifest.md +++ b/.tools/docs/app_manifest.md @@ -115,7 +115,7 @@ The App Centre asks for a few optional fields: `status`, `quickstart`, `screensh | `colab` | A list of Google Colab notebooks, each with a `label` and a `url` on `colab.research.google.com`. Only the notebooks you list are shown. | | `pip` | The name of your package on PyPI. | -`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but no installer is built for them. +`platforms` also decides which installers your releases build. Leave a system out when your app cannot run there. Without `platforms`, every installer is built: `windows-x86_64`, `linux-x86_64`, `macos-arm64` (Apple silicon) and `macos-x86_64` (Intel Macs). `windows-arm64` and `linux-arm64` are accepted, but they build nothing yet: no installer is made for them, and a list with only these two stops the release. ### `hosts`: where your tools are offered @@ -150,7 +150,7 @@ The **Check App Centre manifest** workflow runs when you change the file and whe - If the file is missing, it shows a warning and passes. - If the file is invalid, it fails and says what to fix. This never stops your installers from being built. -- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](keep_app_up_to_date.md). +- It rejects fields it does not know (this catches typos, so the schema is not loosened); the template keeps its copy of the schema in step with the App Centre, see [Keep your app up to date](template_synchronization.md). - It also checks that the icon and screenshots you name exist in the repository. ## Check it yourself diff --git a/.tools/docs/before_getting_started.md b/.tools/docs/before_getting_started.md index fd974a6..cbbed46 100644 --- a/.tools/docs/before_getting_started.md +++ b/.tools/docs/before_getting_started.md @@ -35,6 +35,7 @@ Once installed, the app runs without internet access, unless your notebooks 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). diff --git a/.tools/docs/create_repository.md b/.tools/docs/create_repository.md index e2db347..39347c4 100644 --- a/.tools/docs/create_repository.md +++ b/.tools/docs/create_repository.md @@ -19,7 +19,7 @@ Next: [Initialise your repository](initialise_repository.md). ## Template updates (optional, later) -The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](keep_app_up_to_date.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. +The template keeps improving, and your repository can receive the changes as pull requests. Set this up after your first release: see [Keep your app up to date](template_synchronization.md). Until you do, the weekly **Sync with Template Repository** run stops with the error "Synchronization setup required" whenever a newer template version exists. --- diff --git a/.tools/docs/executable_creation.md b/.tools/docs/executable_creation.md index b90ce74..5194968 100644 --- a/.tools/docs/executable_creation.md +++ b/.tools/docs/executable_creation.md @@ -7,9 +7,10 @@ Publishing a GitHub release builds the installers of your app for Windows (`.exe - At least one notebook uploaded and merged: see [Add or update a notebook](notebook_upload.md). - A version number for the release, in the form `MAJOR.MINOR.PATCH` (for example `0.0.1`). -## Please check before proceeding +## Check before you release -Open the **Actions** tab of your repository and check that no workflow is running. If one is in progress, wait until it finishes: a release started while another workflow runs may build from files that are about to change. +- **The systems you build for.** The release builds only the systems listed under `distribution.platforms` in `labconstrictor-app.yaml`, or every system when that line is missing: see [`distribution` in Describe your app](app_manifest.md#distribution-how-people-get-the-app). Check that the list holds every system your app should run on. +- **Every workflow run is green.** Open the **Actions** tab of your repository. No workflow may still be running: a release started while another workflow runs may build from files that are about to change. The latest run of each workflow must have a green tick, not only have finished: a red cross means its changes, for example your notebook's requirements, did not make it into the repository ([how to read a run](workflow_status.md)). ## 1. Draft a new release @@ -38,9 +39,9 @@ Click **Publish release**. This starts the workflow **Build Release Installers** ## 3. After the release -- Try your installer yourself: [Install an app](install.md), then [Use notebooks after installation](notebook_usage.md). -- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md). -- Receive future template improvements as pull requests: [Keep your app up to date](keep_app_up_to_date.md). +- Try your installer yourself: [Install an app](install.md), then [Open and use an app](notebook_usage.md). +- List your app in the App Centre: [Describe your app for the App Centre](app_manifest.md), then [Submit your app](https://cellmigrationlab.github.io/LabConstrictor-Site/submit/). +- Receive future template improvements as pull requests: [Keep your app up to date](template_synchronization.md). --- diff --git a/.tools/docs/external_code_upload.md b/.tools/docs/external_code_upload.md index c19858c..883a674 100644 --- a/.tools/docs/external_code_upload.md +++ b/.tools/docs/external_code_upload.md @@ -119,7 +119,7 @@ Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > * [← Previous](app_manifest.md)            [🏠 Home](README.md)            -[Next β†’](keep_app_up_to_date.md) +[Next β†’](tools_bridge.md) diff --git a/.tools/docs/install.md b/.tools/docs/install.md index d0c84d5..9bf667b 100644 --- a/.tools/docs/install.md +++ b/.tools/docs/install.md @@ -33,7 +33,7 @@ Download the installer for your system from the app's page in the [App Centre](h ## 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: [Use notebooks after installation](notebook_usage.md). +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 @@ -60,4 +60,4 @@ To run the tools, install the plugin for your image software once: see [Use apps ## Next -Open the app and start working: [Use notebooks after installation](notebook_usage.md). +Open the app and start working: [Open and use an app](notebook_usage.md). diff --git a/.tools/docs/keep_app_up_to_date.md b/.tools/docs/keep_app_up_to_date.md index 5831bee..e97da7f 100644 --- a/.tools/docs/keep_app_up_to_date.md +++ b/.tools/docs/keep_app_up_to_date.md @@ -1,32 +1,3 @@ # Keep your app up to date -The LabConstrictor template keeps improving. Your repository can receive those improvements, including updates to its GitHub Actions workflows, as a pull request that you review and merge. This is optional and can wait until after your first release. - -## How it works - -The **Sync with Template Repository** workflow runs every Monday at 09:00 UTC, and you can also start it yourself from the **Actions** tab. When the template has a newer version than your repository, the workflow applies the changes needed to move your repository to that version and opens a pull request titled "Sync template to version" followed by the new version number. You then merge it as described in [Accept a pull request](accept_pull_request.md). When your repository is already on the latest template version, the run ends without opening a pull request. - -Template-managed files, such as the copy of the App Centre manifest schema used by the **Check App Centre manifest** workflow, are refreshed by the same pull request. If that check rejects a field the App Centre accepts, your copy of the schema is older than the App Centre: merge the latest sync pull request. - -## What you lose without the setup - -Opening that pull request needs a token that you create and save in your repository as the secret `LABCONSTRICTOR_SYNC_TOKEN`. Without it, the workflow stops with the error "Synchronization setup required" as soon as a newer template version exists. No update pull request is created, so your repository stays on the template version it has. - -## Set it up - -Follow [Enable automatic LabConstrictor template updates](template_synchronization.md): create the token, save it as the secret, and renew it when it expires ([Renewing an expired token](template_synchronization.md#renewing-an-expired-token)). - -## If it does not work - -See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions), and [Check the status of GitHub workflows](workflow_status.md) for how to read a failed run. - ---- - -
- -[← Previous](external_code_upload.md)            -[🏠 Home](README.md)            -[Next β†’](template_synchronization.md) - - -
+This page has moved: see [Keep your app up to date](template_synchronization.md). diff --git a/.tools/docs/migration_0_1_38.md b/.tools/docs/migration_0_1_38.md new file mode 100644 index 0000000..4d062b7 --- /dev/null +++ b/.tools/docs/migration_0_1_38.md @@ -0,0 +1,40 @@ +# Template 0.1.38: one first-run page for app users, one update page, clearer guides + +Design note for the 0.1.38 migration (`.template_sync/migrations/v0_1_37_to_v0_1_38.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 + +Two reviews of the website, checked against the template, the repository form and the installer, found: + +* two first-run pages for app users: the template's `notebook_usage.md` and the website's hand-written "Open and use an app" said half of the same things each; +* two update pages: `keep_app_up_to_date.md` explained the sync workflow and sent the reader on to `template_synchronization.md` for the setup; +* `notebook_requirements.md` said both that the form accepts only `package==version` and that the merge keeps ranges such as `numpy>=1.24` as written, without saying where a range can come from (a `requirements.yaml` edited directly on GitHub); +* `personal_access_token.md` ended with "paste the token into your notebook's `GitHub-token` field", which no page has; it did not say where the token is used, why a classic token with `repo` is needed, nor how to set an expiry or revoke it; `before_getting_started.md` did not mention the token; +* `troubleshooting_installed_app.md` gave template version numbers to app users, who cannot see them; +* `executable_creation.md` did not ask to check the systems to build and that the workflows succeeded (not only finished) before a release; +* `tools_bridge.md`, the first page of the "Connect an app" track, was titled "(optional)"; `app_manifest.md` did not say plainly that `windows-arm64` and `linux-arm64` build nothing; a typo in `notebook_upload.md`. + +## 2. What changes + +* `notebook_usage.md` is titled "Open and use an app": open the app, the Welcome notebook, run a notebook (code hiding is shown, not linked), the app's example, napari / Fiji / QuPath, results, Colab, updates, closing, and where to look when something fails. Links to the website are absolute. +* `template_synchronization.md` is titled "Keep your app up to date" and holds both pages. This file name was kept because more pages link to it (the sync workflow, the template README, `troubleshooting.md`, the 0.1.12 migration and the website). `keep_app_up_to_date.md` becomes a pointer page and leaves the docs README; the pages that linked it link `template_synchronization.md`. +* The other guides are corrected as listed in section 1. `install.md`, `create_repository.md`, `external_code_upload.md` and `troubleshooting.md` follow the new titles and links. + +Sixteen files in `.tools/docs/` change (the list is `FILES` in the migration). No code changes. + +## 3. What the migration does + +* Each file is replaced by the 0.1.38 page when it is still the 0.1.37 template file, compared with LF line endings (the frozen copies are in `.template_sync/resources/v0_1_37_to_v0_1_38/previous/`). The file keeps its own line endings. +* `keep_app_up_to_date.md` becomes the pointer page only when it is the 0.1.37 template copy. An app's own version stays (`SKIPPED`, with a note that its content is now in `template_synchronization.md`). Nothing is deleted. +* `.tools/docs/README.md` is replaced only when it is the 0.1.37 template file. In most apps the repository form replaced it with the template's README, so it is skipped with a note of what to change by hand. +* `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 missing file is not created. 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 and take what you want. + +## 5. What is checked here + +* Tests (`tests/test_template_sync_0_1_38.py`): the resources are the live files and differ from the 0.1.37 ones; a 0.1.37 app reaches the live files with LF and CRLF line endings, and a second run changes nothing; a customised file, the pointer page and the docs README are skipped with their notes; a missing file is not created; `external_code_upload.md` with a package name; the sync from 0.1.37 and the chain from older versions. +* The older tests compare with the 0.1.37 files (`tests/_v0_1_38.py`, `before_0_1_38`). diff --git a/.tools/docs/notebook_requirements.md b/.tools/docs/notebook_requirements.md index c686776..291f485 100644 --- a/.tools/docs/notebook_requirements.md +++ b/.tools/docs/notebook_requirements.md @@ -2,6 +2,8 @@ Every notebook you upload needs a `requirements.yaml` file: the Python version and the packages it uses, each with its exact version. The installer installs these packages on your users' computers. +The upload form accepts only exact versions: every dependency must have the form `package==version`. Version ranges such as `numpy>=1.24` can only appear in a `requirements.yaml` that you edit directly in your repository on GitHub, without the form (see [When notebooks ask for different versions of a package](#when-notebooks-ask-for-different-versions-of-a-package)). + There are two ways to make the file: * **Option 1 (automated):** the Requirements Generator notebook reads the packages from the Python environment where your notebook runs. Use it when you start from scratch. @@ -34,7 +36,7 @@ Run its cells in order and follow the instructions in the notebook: choose your Start from the [example requirements.yaml file](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/requirements.yaml). It has three fields: -* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). The upload form refuses ranges such as `pandas>=2`. +* **`dependencies`:** every package the notebook uses, one per line, each starting with `- ` and fixed to one version with `==` (`pandas==2.2.2`). Optional extras are allowed (`colabfold[alphafold,openmm]==1.6.3`). * **`python_version`:** the Python version the notebook runs with (for example `3.11.1`). All notebooks of an app must use the same one. * **`description`:** one sentence on what the notebook does. @@ -81,7 +83,7 @@ The workflow then writes a **lock file** next to each requirements file (`requir ### When notebooks ask for different versions of a package -The merge never changes a notebook's requirement silently. Requirements are kept as written (`numpy>=1.24` stays `numpy>=1.24`), and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: +The merge never changes a notebook's requirement silently. Each requirement is kept as written in the notebook's `requirements.yaml`: a version range you wrote there directly on GitHub (`numpy>=1.24`) stays a range, and the requirements of several notebooks are combined (`numpy>=1.24,<2`). The workflow stops, and no requirements file is written, when: * two notebooks pin a package to different versions (`numpy==1.26.4` and `numpy==2.0.0`); * a pin does not meet another notebook's requirement (`numpy==2.0.0` and `numpy<2`); diff --git a/.tools/docs/notebook_upload.md b/.tools/docs/notebook_upload.md index e0fc1c7..d28a966 100644 --- a/.tools/docs/notebook_upload.md +++ b/.tools/docs/notebook_upload.md @@ -23,7 +23,7 @@ The first cell of every notebook checks its version, so users see when a newer v current_version = "0.0.1" notebook_name = "Notebook_template" # Replace with the actual notebook name -# First of all check if ipywidgets is installed, if not through an informative error +# First of all check if ipywidgets is installed, if not throw an informative error try: import ipywidgets as widgets except ImportError: diff --git a/.tools/docs/notebook_usage.md b/.tools/docs/notebook_usage.md index 209dce7..dea128e 100644 --- a/.tools/docs/notebook_usage.md +++ b/.tools/docs/notebook_usage.md @@ -1,16 +1,18 @@ -# Use notebooks after installation +# Open and use an app -How to open an installed app, run its notebooks and update them. +You installed a LabConstrictor app ([how to install](install.md)). From here: open it, try the app's example, then use your own data. + +Want to see the idea first? The [interactive demo](https://cellmigrationlab.github.io/LabConstrictor-Site/demo/) lets you try a notebook, napari and Fiji with example data before you install anything. ## Open the app -To open the application, go to the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux). Search for the application name and click its icon to start it. +Start the app from the Start Menu (Windows), the Applications folder (macOS) or your applications menu (Linux): search for its name and click its icon. -A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the Welcome notebook: +A terminal window opens first. It keeps JupyterLab running: leave it open while you work. After a few seconds, JupyterLab opens in your web browser with the **Welcome notebook**: ![Welcome Notebook](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Welcome_Notebook.png) -## Open a notebook +## Open a notebook from the Welcome notebook Run the cell of the Welcome notebook. It shows a table of the app's notebooks, with their version and whether a newer version exists. Click **Open the notebook** in the last column to open a notebook in a new tab. @@ -18,7 +20,31 @@ If the app's repository on GitHub is private, the Welcome notebook asks for a Gi ## Run a notebook -Notebooks made with LabConstrictor can hide their code. Run each cell with its play button, or select the cell and click the play button in the top toolbar. The **Show/Hide Code** button in the toolbar shows the code. See [Hide code cells in notebooks](code_hiding.md) for pictures. If you are new to JupyterLab, see [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). +Follow the instructions written in the notebook, and run its cells from top to bottom. Notebooks made with LabConstrictor often hide their code. Run a cell with the play button next to it, if there is one, or select the cell and click the play button in the top toolbar: + +![Toolbar Play Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Play_Button.png) + +The **Show/Hide Code** button in the top toolbar shows or hides the code of every cell: + +![Show Hide Code Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_ShowHide_Button.png) + +New to JupyterLab? See [this JupyterLab guide](https://github.com/CellMigrationLab/docs-hub/blob/main/docs/JupyterLab/JupyterLab_Guide.md). + +## Try the app's example + +Look for an example in the app's documentation: the **Documentation** or **README** link on its page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/). If it has one, run it first and compare your result with the one it describes. What an app does, and what its notebooks expect, is described there. + +## Use it in napari, Fiji or QuPath + +Some apps also have **tools**: analyses you run from napari, Fiji or QuPath on the image you have open, with a form for the settings and the results drawn on the image. The app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) shows which programs it works in. Install the plugin for your program once: [Use apps inside napari, Fiji and QuPath](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/image-software/) explains how. + +## Keep your results + +Each notebook decides where it writes its results. Note the folder it names before you close JupyterLab, and copy what you want to keep. + +## Use it without installing + +Many apps also run in Google Colab. The app's page in the [App Centre](https://cellmigrationlab.github.io/LabConstrictor-Site/apps/) lists its Colab notebooks and, when it has one, a pip command. ## Update a notebook @@ -31,11 +57,14 @@ Your current copy, with your changes and outputs, is kept as `.backup- ## Close the app -Keep the terminal window open until you have finished working with your notebooks. When you have, stop the Jupyter Lab session with **File > Shut Down** in Jupyter Lab (or click on the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. +When you have finished, stop JupyterLab with **File > Shut Down** (or click the terminal window and press `Ctrl+C`). The terminal then asks you to press `Enter`, and closes. ## If something does not work -See [Troubleshooting an installed app](troubleshooting_installed_app.md). +- Windows and macOS warn about installers that are not code-signed yet, and both have a way to continue: see [Install an app](install.md). +- [Troubleshooting an installed app](troubleshooting_installed_app.md) covers problems with an app on your computer. +- [Find your problem](https://cellmigrationlab.github.io/LabConstrictor-Site/guides/help/) lists what you may see and where each is explained. +- Open an issue in the app's repository: the **Report a problem** link on its page in the App Centre, when the repository has an issue tracker. --- diff --git a/.tools/docs/personal_access_token.md b/.tools/docs/personal_access_token.md index b0632c7..404a640 100644 --- a/.tools/docs/personal_access_token.md +++ b/.tools/docs/personal_access_token.md @@ -2,28 +2,35 @@ > Looking for the token used by the automatic template update workflow? Follow the dedicated [automatic template synchronization guide](template_synchronization.md). It uses a repository-scoped fine-grained token with a different purpose and secret name. -If you want to work with GitHub repositories from your notebook, like cloning, editing, or pushing files, you’ll need a GitHub Personal Access Token (PAT). This token lets you authenticate your API calls and gives you the right permissions. The GIF below shows the steps to create a token. +A GitHub personal access token lets LabConstrictor act on your repositories as you. You need one for: -![Gif of generating a GitHub token](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/GitHub_Access_Token.gif) +- the [repository initialiser](initialise_repository.md) and the [notebook upload form](notebook_upload.md): they open a pull request in your repository; +- the Welcome notebook, and the version check in the first cell of each notebook, of an installed app whose repository is private: they read the newest notebook versions from the repository (in the Welcome notebook, enter the token and click **Load Private GitHub Repo**). -> The LabConstrictor repository form accepts only a classic token, which starts with `ghp_`. A fine-grained token (it starts with `github_pat_`) is rejected. +The forms accept only a classic token, which starts with `ghp_`, and reject a fine-grained token (it starts with `github_pat_`). A classic token needs the **repo** scope to write to a repository and to read a private one. -To see the full steps, follow the instructions below. +![Gif of generating a GitHub token](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/GitHub_Access_Token.gif) ## Create the token -1. Go to https://github.com/ and sign in. -2. Click your profile icon (top right) βž” **Settings** -3. In the left sidebar, select **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)** -4. On the top right side (at the same level as `Personal access tokens (classic)`), click on **Generate new token** βž” **Generate new token (classic)** -5. Give your token a descriptive **Name** (e.g., `Notebook RW Token`) and set an **Expiration** if desired -6. Under **Scopes**, tick **repo** - - *(Optional: To only work with public repositories, select **public_repo** instead of **repo**)* -7. Click **Generate token** at the bottom -8. **Copy** your new token right away. You won’t be able to see it again later! -9. Paste the token into your notebook’s `GitHub-token` field, so API calls authenticate as the chosen owner. - -A classic token with the **repo** scope can read and write your repositories, so keep it private. +1. Go to https://github.com/ and sign in. +2. Click your profile icon (top right) βž” **Settings**. +3. In the left sidebar, select **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)**. +4. Click **Generate new token** βž” **Generate new token (classic)**. +5. Give your token a descriptive **Note** (for example `LabConstrictor forms`) and set an **Expiration**. We recommend one: an expired token stops working by itself if you forget it. +6. Under **Scopes**, tick **repo**. If all your repositories are public, **public_repo** is enough. +7. Click **Generate token** at the bottom. +8. **Copy** your new token right away. GitHub shows it only once. +9. Paste it where it is asked for: the **Personal Access Token** field of the repository initialiser or of the notebook upload form, or the **Personal Access Token** field of the Welcome notebook or of a notebook's first cell. + +A classic token with the **repo** scope can read and write all your repositories: keep it private, and do not save it in a notebook or a file in your repository. + +## Renew or revoke the token + +Open **Settings** βž” **Developer settings** βž” **Personal access tokens** βž” **Tokens (classic)**: + +- **Renew:** click the token's name, then **Regenerate token**, choose a new expiration and copy the new token. The old one stops working. +- **Revoke:** click **Delete** next to the token. Do this as soon as you no longer need it, or if it may have been seen by someone else. --- diff --git a/.tools/docs/template_synchronization.md b/.tools/docs/template_synchronization.md index d9c0d42..9b5436c 100644 --- a/.tools/docs/template_synchronization.md +++ b/.tools/docs/template_synchronization.md @@ -1,8 +1,14 @@ -# Enable automatic LabConstrictor template updates +# Keep your app up to date -The **Sync with Template Repository** workflow checks the LabConstrictor template every week. When a newer template version exists, it opens a pull request in your repository with the changes, for you to review and merge. +The LabConstrictor template keeps improving. Your repository can receive those improvements, including updates to its GitHub Actions workflows, as a pull request that you review and merge. This is optional and can wait until after your first release. -To open that pull request, the workflow needs a token that you create once and save in your repository. The token gives access only to the repository you select, not to your other repositories. +## How it works + +The **Sync with Template Repository** workflow runs every Monday at 09:00 UTC, and you can also start it yourself from the **Actions** tab. When the template has a newer version than your repository, the workflow applies the changes needed to move your repository to that version and opens a pull request titled "Sync template to version" followed by the new version number. You then merge it as described in [Accept a pull request](accept_pull_request.md). When your repository is already on the latest template version, the run ends without opening a pull request. + +Template-managed files, such as the copy of the App Centre manifest schema used by the **Check App Centre manifest** workflow, are refreshed by the same pull request. If that check rejects a field the App Centre accepts, your copy of the schema is older than the App Centre: merge the latest sync pull request. + +To open that pull request, the workflow needs a token that you create once and save in your repository as the secret `LABCONSTRICTOR_SYNC_TOKEN`. The token gives access only to the repository you select, not to your other repositories. Without it, the workflow stops with the error "Synchronization setup required" as soon as a newer template version exists, and your repository stays on the template version it has. ## What you need @@ -73,13 +79,13 @@ When the token expires, runs fail with an authentication error such as "Bad cred ## If something does not work -See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions). +See [Synchronisation is failing on GitHub Actions](troubleshooting.md#synchronisation-is-failing-on-github-actions), and [Check the status of GitHub workflows](workflow_status.md) for how to read a failed run. ---
-[← Previous](keep_app_up_to_date.md)            +[← Previous](tools_bridge.md)            [🏠 Home](README.md)            [Next β†’](notebook_portability.md) diff --git a/.tools/docs/tools_bridge.md b/.tools/docs/tools_bridge.md index f96331e..cec1b8f 100644 --- a/.tools/docs/tools_bridge.md +++ b/.tools/docs/tools_bridge.md @@ -1,4 +1,4 @@ -# Expose your app's tools to napari, Fiji and QuPath (optional) +# 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. diff --git a/.tools/docs/troubleshooting.md b/.tools/docs/troubleshooting.md index 5f68a97..4bf8fc9 100644 --- a/.tools/docs/troubleshooting.md +++ b/.tools/docs/troubleshooting.md @@ -4,7 +4,7 @@ Problems with your repository on GitHub. For problems with an installed app on y ## Synchronisation is failing on GitHub Actions -The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Enable automatic LabConstrictor template updates](template_synchronization.md). +The **Sync with Template Repository** workflow needs the repository secret `LABCONSTRICTOR_SYNC_TOKEN`, because template updates can change files in `.github/workflows/`. The setup is in [Keep your app up to date](template_synchronization.md). ### "Synchronization setup required": the token is missing diff --git a/.tools/docs/troubleshooting_installed_app.md b/.tools/docs/troubleshooting_installed_app.md index 76cf272..e011770 100644 --- a/.tools/docs/troubleshooting_installed_app.md +++ b/.tools/docs/troubleshooting_installed_app.md @@ -28,7 +28,7 @@ The app is then removed from the list. ## Windows asks for administrator rights for python.exe while uninstalling -Uninstalling an app made with template 0.1.20 or earlier may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. +Uninstalling an older release of an app may show a User Account Control prompt: "Do you want to allow this app from an unknown publisher to make changes to your device? python.exe", with the program location `"\python.exe" -m conda.core.initialize ...`. 1. Click **No**. The prompt is not needed. 2. The uninstaller then shows a "Failed to clean AutoRun" error with Abort, Retry and Ignore: click **Ignore**. @@ -37,13 +37,15 @@ The uninstall then finishes normally, and nothing outside the app folder is chan Do not click **Abort**, even though it is the default button: it stops the uninstall halfway and leaves the app folder on disk. If that happened, run `Uninstall-.exe` in the app folder again. -Installers built with template 0.1.21 or later do not have this problem ([details](migration_0_1_21.md)). +Newer releases of the app do not have this problem: install the newest release of the app. ## The notebook fails with "No module named ..." although the installation finished -The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This happens with apps made with template 0.1.23 or earlier when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. +The first cell that imports the app fails with `ModuleNotFoundError: No module named ''`. This can happen with an older release of an app when someone once ran `python -m ipykernel install --user` on the computer (common with Anaconda or pip setups). Jupyter then has a personal "python3" kernel, and the app's notebooks run in that other Python instead of the app's own. -Install a release made with template 0.1.24 or later: it always uses the app's own Python. Until then, you can delete the personal kernel folder, but the other Jupyter installations on the computer that use it lose it too: +Install the newest release of the app: newer releases always use the app's own Python. + +Advanced, if you cannot install a newer release: delete the personal kernel folder. The other Jupyter installations on the computer that use it lose it too. - Linux: `~/.local/share/jupyter/kernels/python3` - macOS: `~/Library/Jupyter/kernels/python3` @@ -51,7 +53,7 @@ Install a release made with template 0.1.24 or later: it always uses the app's o ## My changes to a notebook are gone after an update -The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Apps made with template 0.1.30 or earlier replace the notebook without keeping a copy. +The **Update** button of the Welcome notebook keeps your copy before it replaces a notebook: look for `.backup-.ipynb` in the same folder and open it in JupyterLab. Older releases of some apps replace the notebook without keeping a copy: install the newest release of the app to get this backup. ## JupyterLab does not start because Windows reports an ASN.1 certificate error diff --git a/.tools/templates/download_executable_template.md b/.tools/templates/download_executable_template.md index e5404cb..80acc60 100644 --- a/.tools/templates/download_executable_template.md +++ b/.tools/templates/download_executable_template.md @@ -34,7 +34,7 @@ After installation, you can launch PROJECT_NAME from your desktop app or from th ![Launch PROJECT_NAME](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Windows_Launch.gif) -Then, start using it following the instructions on the [Usage of Notebooks After Installation](./notebook_usage.md) guide. +Then, start using it following the instructions on the [Open and use an app](./notebook_usage.md) guide. --- @@ -80,7 +80,7 @@ bash PROJECT_NAME-VERSION_NUMBER-Linux-x86_64.sh ## 4. Launch PROJECT_NAME -After installation, you can launch PROJECT_NAME from your applications menu and start using it following the instructions on the [Usage of Notebooks After Installation](./notebook_usage.md) guide. +After installation, you can launch PROJECT_NAME from your applications menu and start using it following the instructions on the [Open and use an app](./notebook_usage.md) guide. --- @@ -133,7 +133,7 @@ Follow the guidelines shown on the following GIF or the instructions bellow: ## 4. Launch PROJECT_NAME -After installation, you can launch PROJECT_NAME from your Applications folder and start using it following the instructions on the [Usage of Notebooks After Installation](./notebook_usage.md) guide. +After installation, you can launch PROJECT_NAME from your Applications folder and start using it following the instructions on the [Open and use an app](./notebook_usage.md) guide. @@ -177,7 +177,7 @@ Follow the guidelines shown on the following GIF or the instructions bellow: ## 4. Launch PROJECT_NAME -After installation, you can launch PROJECT_NAME from your Applications folder and start using it following the instructions on the [Usage of Notebooks After Installation](./notebook_usage.md) guide. +After installation, you can launch PROJECT_NAME from your Applications folder and start using it following the instructions on the [Open and use an app](./notebook_usage.md) guide. diff --git a/tests/_v0_1_37.py b/tests/_v0_1_37.py index 913dfd6..89bd3b6 100644 --- a/tests/_v0_1_37.py +++ b/tests/_v0_1_37.py @@ -10,6 +10,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_38 import before_0_1_38 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_36_to_v0_1_37.py" @@ -25,6 +27,7 @@ def _migration() -> ModuleType: def before_0_1_37(relative: Path | str, data: bytes) -> bytes: """`data` (a live template file at `relative`) without the 0.1.37 change; any other file is returned as it is.""" + data = before_0_1_38(relative, data) migration = _migration() relative = Path(relative) if relative not in migration.FILES: diff --git a/tests/_v0_1_38.py b/tests/_v0_1_38.py new file mode 100644 index 0000000..1eacb22 --- /dev/null +++ b/tests/_v0_1_38.py @@ -0,0 +1,38 @@ +"""Helper of the tests: a live template file as it was before template 0.1.38. + +Template 0.1.38 replaces sixteen files in .tools/docs whole (FILES of the migration). The tests of the older migrations compare with +the live files; `before_0_1_38` gives the bytes of a live file without the 0.1.38 change (the frozen 0.1.37 copy when the file is the 0.1.38 +page), so they keep checking what they checked. The 0.1.38 changes are tested in test_template_sync_0_1_38.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_37_to_v0_1_38.py" + + +def _migration() -> ModuleType: + spec = importlib.util.spec_from_file_location("migration_0_1_38_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_38(relative: Path | str, data: bytes) -> bytes: + """`data` (a live template file at `relative`) without the 0.1.38 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.38 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_20.py b/tests/test_template_sync_0_1_20.py index 995749f..963295e 100644 --- a/tests/test_template_sync_0_1_20.py +++ b/tests/test_template_sync_0_1_20.py @@ -19,6 +19,7 @@ import yaml from _v0_1_24 import before_0_1_24 +from _v0_1_38 import before_0_1_38 ROOT = Path(__file__).resolve().parents[1] @@ -102,7 +103,9 @@ def test_the_live_scripts_hold_the_new_blocks_once(self) -> None: self.assertEqual(bump.count(MIGRATION.BUMP_SNIPPET + MIGRATION.BUMP_FUNCTION_ANCHOR), 1) self.assertEqual(bump.count(MIGRATION.BUMP_CALL_NEW), 1) self.assertIn(MIGRATION.UV_PIN, lf(ROOT / MIGRATION.TOOLS_REQUIREMENTS).splitlines()) - self.assertIn(MIGRATION.USAGE_NEW, lf(ROOT / MIGRATION.USAGE_DOC)) + # 0.1.38 rewrites the usage guide whole (tests/_v0_1_38.py): the 0.1.37 page holds the 0.1.20 sentence. + usage = before_0_1_38(MIGRATION.USAGE_DOC, (ROOT / MIGRATION.USAGE_DOC).read_bytes()).decode("utf-8").replace("\r\n", "\n") + self.assertIn(MIGRATION.USAGE_NEW, usage) def test_the_menu_shortcut_closes_the_windows_terminal_after_enter(self) -> None: data = json.loads(lf(ROOT / MIGRATION.MENU)) diff --git a/tests/test_template_sync_0_1_21.py b/tests/test_template_sync_0_1_21.py index 24a06f2..ddb5b39 100644 --- a/tests/test_template_sync_0_1_21.py +++ b/tests/test_template_sync_0_1_21.py @@ -13,6 +13,8 @@ from pathlib import Path from types import ModuleType +from _v0_1_38 import before_0_1_38 + ROOT = Path(__file__).resolve().parents[1] MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_20_to_v0_1_21.py" @@ -59,7 +61,9 @@ def test_the_design_note_and_troubleshooting_entry_are_linked(self) -> None: # the design note is linked from its migration (DOCS_URL); since 0.1.29 the docs README no longer lists design notes self.assertIn(".tools/docs/migration_0_1_21.md", (ROOT / ".template_sync/migrations/v0_1_20_to_v0_1_21.py").read_text(encoding="utf-8")) self.assertTrue((ROOT / ".tools/docs/migration_0_1_21.md").is_file()) - self.assertIn("(migration_0_1_21.md)", (ROOT / ".tools/docs/troubleshooting_installed_app.md").read_text(encoding="utf-8")) + # 0.1.38 drops template versions from the app users' page (tests/_v0_1_38.py): the 0.1.37 page links the note. + page = Path(".tools/docs/troubleshooting_installed_app.md") + self.assertIn(b"(migration_0_1_21.md)", before_0_1_38(page, (ROOT / page).read_bytes())) def test_the_live_script_holds_the_new_block_once_and_pins_26_9_3(self) -> None: text = live_text() diff --git a/tests/test_template_sync_0_1_37.py b/tests/test_template_sync_0_1_37.py index ae11571..2d5ed91 100644 --- a/tests/test_template_sync_0_1_37.py +++ b/tests/test_template_sync_0_1_37.py @@ -15,6 +15,7 @@ from types import ModuleType from _v0_1_36 import before_0_1_36 +from _v0_1_38 import before_0_1_38 ROOT = Path(__file__).resolve().parents[1] @@ -42,7 +43,8 @@ def lf(path: Path) -> str: def live(relative: Path) -> bytes: - return (ROOT / relative).read_bytes() + """The 0.1.37 template file: the live file without the 0.1.38 change (tests/_v0_1_38.py).""" + return before_0_1_38(relative, (ROOT / relative).read_bytes()) def previous(relative: Path) -> bytes: diff --git a/tests/test_template_sync_0_1_38.py b/tests/test_template_sync_0_1_38.py new file mode 100644 index 0000000..4aed89a --- /dev/null +++ b/tests/test_template_sync_0_1_38.py @@ -0,0 +1,279 @@ +"""Tests of the 0.1.38 migration: the merged and corrected guides replace the 0.1.37 files 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_37 import before_0_1_37 + + +ROOT = Path(__file__).resolve().parents[1] +MIGRATION_PATH = ROOT / ".template_sync/migrations/v0_1_37_to_v0_1_38.py" +SYNC_PATH = ROOT / ".template_sync/sync.py" +DOCS = ROOT / ".tools/docs" +# The guides a first-time reader follows to the end: the website checks that each has these level-2 headings. +CRITICAL = ("install.md", "initialise_repository.md", "notebook_requirements.md", "notebook_upload.md", "executable_creation.md") +WANTED = (("what you need", "before you start"), ("check that it worked",), ("if something does not work",)) + + +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_38") + + +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.37 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\.(3[8-9]|[4-9][0-9])\b") + self.assertIn(" - from: 0.1.37\n to: 0.1.38\n script: migrations/v0_1_37_to_v0_1_38.py\n", text) + + def test_chains_from_older_versions_reach_0_1_38(self) -> None: + sync = load(SYNC_PATH, "sync_for_0_1_38") + manifest = sync.parse_manifest(ROOT / ".template_sync/manifest.yaml") + for start in ("0.0.0", "0.1.16", "0.1.36", "0.1.37"): + chain = sync.resolve_migration_chain(manifest["migrations"], start, "0.1.38") + self.assertEqual(chain[-1]["to"], "0.1.38", start) + + def test_the_design_note_exists_and_is_not_in_the_docs_index(self) -> None: + self.assertIn(".tools/docs/migration_0_1_38.md", MIGRATION_PATH.read_text(encoding="utf-8")) + self.assertTrue((DOCS / "migration_0_1_38.md").is_file()) + self.assertNotIn("migration_0_1_38.md", lf(DOCS / "README.md")) + + def test_the_resources_are_the_live_files_and_the_0_1_37_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_37_files(self) -> None: + for relative in MIGRATION.FILES: + with self.subTest(file=str(relative)): + self.assertEqual(before_0_1_37(relative, live(relative)), before_0_1_37(relative, previous(relative))) + + def test_the_critical_guides_have_the_sections_the_website_checks(self) -> None: + for name in (*CRITICAL, "template_synchronization.md"): + headings = [line[3:].strip().lower() for line in lf(DOCS / name).splitlines() if line.startswith("## ")] + for options in WANTED: + with self.subTest(guide=name, section=options[0]): + self.assertTrue(any(h in options for h in headings)) + + def test_the_first_run_page_for_app_users(self) -> None: + text = lf(DOCS / "notebook_usage.md") + self.assertTrue(text.startswith("# Open and use an app\n")) + for url in ("apps/", "guides/help/", "demo/", "guides/image-software/"): + self.assertIn(f"](https://cellmigrationlab.github.io/LabConstrictor-Site/{url})", text) + self.assertNotIn("](code_hiding.md)", text, "code hiding is shown on the page, not linked") + + def test_one_update_page_and_a_pointer(self) -> None: + self.assertTrue(lf(DOCS / "template_synchronization.md").startswith("# Keep your app up to date\n")) + self.assertIn("](template_synchronization.md)", lf(MIGRATION.RESOURCE_ROOT / MIGRATION.POINTER_PAGE)) + self.assertLessEqual(len(lf(DOCS / "keep_app_up_to_date.md").strip().splitlines()), 3) + index = lf(DOCS / "README.md") + self.assertNotIn("keep_app_up_to_date.md", index) + self.assertIn("- [Open and use an app](notebook_usage.md)", index) + for page in DOCS.glob("*.md"): + if page.name.startswith("migration_") or page.name == "keep_app_up_to_date.md": + continue + with self.subTest(page=page.name): + self.assertNotIn("](keep_app_up_to_date.md", lf(page)) + + def test_app_users_see_no_template_versions(self) -> None: + self.assertNotRegex(lf(DOCS / "troubleshooting_installed_app.md"), r"template( version)? 0\.\d") + self.assertNotRegex(lf(DOCS / "notebook_usage.md"), r"0\.\d+\.\d+") + + def test_the_tools_guide_title_and_the_token_page(self) -> None: + self.assertTrue(lf(DOCS / "tools_bridge.md").startswith("# Expose your app's tools to napari, Fiji and QuPath\n")) + token = lf(DOCS / "personal_access_token.md") + self.assertNotIn("GitHub-token", token) + for words in ("ghp_", "**repo**", "Expiration", "Delete", "Load Private GitHub Repo"): + self.assertIn(words, token) + self.assertIn("](personal_access_token.md)", lf(DOCS / "before_getting_started.md")) + self.assertIn("](personal_access_token.md)", lf(DOCS / "initialise_repository.md")) + + def test_the_footers_follow_the_docs_index(self) -> None: + index = re.findall(r"\]\(([a-z_0-9]+\.md)\)", lf(DOCS / "README.md")) + position = index.index("template_synchronization.md") + text = lf(DOCS / "template_synchronization.md") + self.assertIn(f"[← Previous]({index[position - 1]})", text) + self.assertIn(f"[Next β†’]({index[position + 1]})", text) + position = index.index("external_code_upload.md") + self.assertIn(f"[Next β†’]({index[position + 1]})", lf(DOCS / "external_code_upload.md")) + + def test_the_relative_links_of_the_pages_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_38_")) + 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_37_gets_the_pages_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_and_the_others_change(self) -> None: + relative = Path(".tools/docs/troubleshooting.md") + own = previous(relative) + b"\n## Our own problem\n\nOur own fix.\n" + page = self.put(relative, own) + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised (not the 0.1.37 template file)", log) + self.assertNotIn("By hand", log) + self.assertEqual(page.read_bytes(), own) + self.assertIn(f"done: {len(MIGRATION.FILES) - 1} file(s) changed", log) + + def test_a_customised_pointer_page_is_kept_with_a_note(self) -> None: + relative = MIGRATION.POINTER_PAGE + own = previous(relative) + b"\nOur own update notes.\n" + page = self.put(relative, own) + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised", log) + self.assertIn("By hand: its content is now in template_synchronization.md", log) + self.assertEqual(page.read_bytes(), own) + + def test_the_app_index_written_by_the_form_is_kept_with_a_note(self) -> None: + """The repository form moves the template README to .tools/docs/README.md (with .tools/docs replaced by .).""" + relative = MIGRATION.DOCS_INDEX + own = (ROOT / "README.md").read_bytes().replace(b".tools/docs", b".") + page = self.put(relative, own) + log = self.run_migration() + self.assertIn(f"{relative}: SKIPPED: customised", log) + self.assertIn("By hand: if it lists keep_app_up_to_date.md, remove that entry", log) + self.assertEqual(page.read_bytes(), own) + + def test_the_external_code_guide_with_the_package_name(self) -> None: + relative = MIGRATION.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.38 page (with the package name celltools)", log) + self.assertEqual(page.read_bytes(), live(relative).replace(b"PYTHON_PROJ_NAME", b"celltools")) + again = self.run_migration() + self.assertIn(f"{relative}: unchanged: already up to date", again) + mixed = previous(relative).replace(b"PYTHON_PROJ_NAME", b"celltools", 1).replace(b"PYTHON_PROJ_NAME", b"other") + self.put(relative, mixed) + self.assertIn(f"{relative}: SKIPPED", 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/install.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.38 (later templates add migrations). + manifest.write_text(with_version(manifest.read_text(encoding="utf-8"), "0.1.38"), encoding="utf-8") + command = [sys.executable, str(self.repo / ".template_sync/sync.py"), "--from-version", start, "--to-version", "0.1.38", "--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_37(self) -> None: + result = self.sync("0.1.37") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("[migration 0.1.38]", result.stdout) + self.assert_template_state() + again = self.sync("0.1.37") + self.assertIn("[migration 0.1.38] done: no repository changes were required", again.stdout) + + def test_the_sync_chain_from_0_1_36_reaches_the_live_pages(self) -> None: + """0.1.37 replaces the 0.1.36 usage guide, then 0.1.38 replaces it again.""" + relative = Path(".tools/docs/notebook_usage.md") + self.put(relative, before_0_1_37(relative, previous(relative))) + self.assertNotEqual((self.repo / relative).read_bytes(), previous(relative)) + result = self.sync("0.1.36") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual((self.repo / relative).read_bytes(), live(relative), result.stdout) + +if __name__ == "__main__": + unittest.main()