Initial commit

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: qt libs
+        uses: tlambert03/setup-qt-libs@v1
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - uses: aganders3/headless-gui@v2
+        name: Build workshop
+        with:
+          run: |
+            pip install -r requirements.txt
+            jupyter book build napari-workshops
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'napari-workshops/_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+.ipynb_checkpoints
+napari-workshops/_build/

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, the napari community
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,28 @@
+# napari-workshop-template
+
+A JupyterBook template for napari workshops.
+
+**To see the built website, go to
+https://<your_github_username>.github.io/napari-workshop-template**. For
+example, see this template [here](https://napari.org/napari-workshop-template/home.html).
+
+**To see a live version where you can execute the notebooks on your browser, use [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/napari/napari-workshop-template/main)** (make sure this link points to your own repository!)
+
+## What is this repository?
+
+This repository is meant to be [forked](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and edited so that you have a starting point when creating your own napari workshop. All instructions below are meant to be executed _on your own fork_, so that you have a copy of the template that you can adjust to your needs.
+
+You can also click the `Use this template` button in the GitHub web interface for this repository:
+
+![Use this template button on GitHub interface](napari-workshops/docs/images/00-template.png)
+
+> [!TIP]
+> Once you have created your workshop, if you would like the event to be listed [in the workshops page in napari.org](https://napari.org/stable/further-resources/napari-workshops.html), feel free to [submit a pull request to the napari/docs repository](https://github.com/napari/docs/blob/main/docs/further-resources/napari-workshops.md).
+
+## Documentation
+
+To learn more about how to build, publish, share and cite your workshop materials, check the [Build your own workshop section](https://napari.github.io/napari-workshop-template/docs/build_your_workshop.html).
+
+## Contributing to this repository
+
+If you find typos, incomplete or misleading instructions, or have suggestions for improvements to this template, open an issue at the napari/napari-workshop-template repo.

binder/apt.txt

@@ -0,0 +1,16 @@
+dbus-x11
+firefox
+xfce4
+xfce4-panel
+xfce4-session
+xfce4-settings
+xorg
+xubuntu-icon-theme
+libx11-xcb-dev
+libglu1-mesa-dev
+libxrender-dev
+libxi-dev
+libxkbcommon-dev
+libxkbcommon-x11-dev
+libqt5x11extras5-dev
+libxcb-xinerama0

binder/environment.yml

@@ -0,0 +1,12 @@
+name: binder
+channels:
+  - conda-forge
+dependencies:
+  - python=3.9
+  - jupyter-server-proxy>=1.4
+  - jupytext
+  - pip
+  - websockify
+  - libxcb
+  - pip:
+    - jupyter-desktop-server

binder/postBuild

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+pip install -r requirements.txt

environment.yml

@@ -0,0 +1,12 @@
+name: workshop
+channels:
+  - conda-forge
+dependencies:
+  - jupyterlab
+  - jupytext
+  - matplotlib
+  - napari
+  - pip
+  - pip:
+    - jupyter-book
+    - napari-animation

napari-workshops/_config.yml

@@ -0,0 +1,43 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: napari workshop template
+author: napari core developers
+logo: logo.ico
+
+# Only build files in the table of contents.
+only_build_toc_files: true
+
+launch_buttons:
+  notebook_interface : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
+  binderhub_url : https://mybinder.org  # The URL of the BinderHub (e.g., https://mybinder.org)
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: "cache"
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: napari_workshop.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/napari/napari-workshop-template  # Online location of your book
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+  path_to_book: "napari-workshops"  # A path to your book's folder, relative to the repository root.
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: false
+  use_repository_button: true
+
+sphinx:
+  config:
+    html_show_copyright: false

napari-workshops/_toc.yml

@@ -0,0 +1,27 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: home
+chapters:
+- file: docs/build_your_workshop
+  sections:
+  - file: docs/deployment_guide
+  - file: docs/launching_binder
+- file: getting_started
+  sections:
+  - file: installation
+  - file: notebook_setup
+- file: notebooks/index
+  sections:
+  - file: notebooks/intro_bioimage_visualization
+  - file: notebooks/spot_detection
+  - file: notebooks/segmenting_and_measuring_nuclei_stardist
+  - file: notebooks/manual_annotation
+  - file: notebooks/custom_colormaps
+  - header: "Alternative Spot Detection Notebooks"
+    sections:
+    - file: notebooks/spot_detection_basics
+    - file: notebooks/spot_detection_functions
+
+- file: make_a_simple_plugin

napari-workshops/docs/build_your_workshop.md

@@ -0,0 +1,135 @@
+# Build your own workshop
+
+```{note}
+This section is about building your own workshop - it should probably be removed
+from your workshop material once you have adapted it to your needs.
+```
+
+## Build locally
+
+To build this workshop locally and preview the generated materials in html format (as a webpage), follow the steps below.
+
+### 1. Install all required packages
+
+First, [fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone it to your local system by
+
+```
+git clone [email protected]:<your-username>/napari-workshop-template.git
+```
+
+In a console/terminal, after installing python on your system using the
+distribution of your choice, and ideally
+[using a virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/), navigate to the napari-workshop-template folder,
+run
+
+```
+python -m pip install -r requirements.txt
+```
+
+### 2. Update the configuration files for the website
+
+You will want to update `napari-workshops/_toc.yml` and `napari-workshops/_config.yml` to 
+suit the needs of your workshop. These two files will determine how the website is rendered.
+
+In `_toc.yml` you can put the Markdown files you want to be rendered in the order you want them.
+
+```{important}
+You don't use the `.md` extension, just the name of the file.
+```
+
+Use the existing file as a template and adjust it to suit your needs. For example, we recommend
+removing *this section* on building the workshop from your final workshop materials.
+For more information, see the [official Jupyter Book Table of Contents documentation](https://jupyterbook.org/customize/toc.html).
+
+In `_config.yml` you can customize the build of the website. Be sure and take a look at, at a minimum:
+- `title` and `author` information at the top: adjust the title as needed and add your name to the authors!
+- the `repository` section towards the bottom: replace the URL of the template repository with your repository—this will be what the GitHub logo links to in your website—and ensure the `path_to_book` matches what you are using—you don't need to change this if you didn't change the layout of the repository.
+
+If you're curious about the other settings already in the file or the range of available options, see [the official official Jupyter Book documentation](https://jupyterbook.org/customize/config.html).
+
+### 3. Building your book locally
+
+To render the html version of your book, including autogenerating figures or
+running Jupyter notebooks, run
+
+```
+jupyter book build napari-workshops
+```
+
+where `napari-workshops` is the name of the folder where your book is stored.
+The rendered version of the workshop materials will be under
+`napari-workshops/_build/html`. For more information, see the
+[JupyterBook documentation](https://jupyterbook.org/).
+
+**Note:** The html files built by the `jupyter book` commands do not need to be
+stored on GitHub, so we added the following path to our `.gitignore` file:
+
+```
+napari-workshops/_build/
+```
+
+## Publish and share your workshop
+### Publish your workshop materials as a static web page
+
+If you want to set up this material to be published as a website from your fork, using [GitHub pages](https://pages.github.com/), follow the steps below.
+
+```{important}
+For this to work, you need to have GitHub pages enabled on your GitHub account. To do this, follow the [deployment guide](deployment_guide).
+```
+
+1. Edit the `.github/workflows/pages.yml` file in your workshop folder to
+   include any installation or setup requirements. By default, the following
+   commands are run as a setup and build step:
+
+    ```
+    - name: Build workshop
+      run: |
+        python -m pip install -r requirements.txt
+        jupyter book build napari-workshops
+    ```
+
+2. Edit the `.github/workflows/pages.yml` file in your workshop folder to
+   set up the desired folder there the (html) built artifacts are stored. By
+   default, the artifacts are in the following path:
+
+    ```
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: 'napari-workshops/_build/html'
+    ```
+
+As currently configured, whenever a new commit is added to the `main` branch of the repository, a new deployment is made: the Jupyter book is built and the
+generated pages are uploaded to [GitHub pages](https://docs.github.com/en/pages/quickstart). 
+
+After GitHub pages is set up for your repository, you will find the workshop materials at
+
+```
+https://<your-username>.github.io/<workshop-name>
+```
+
+For this template, the built site is at
+
+https://napari.github.io/napari-workshop-template
+
+## Index your workshop using Zenodo (for citation purposes)
+
+If you want people to be able to cite your workshop materials, you can create
+a DOI for it using [Zenodo](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content).
+
+Select Creative Commons Attribution 4.0 International (CC-BY 4.0) license if you want attribution.
+
+## Enable a citation file for your repository
+
+Check [the GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) for more details on how to use the `citation.cff` file to enable others to cite your repository.
+
+## Upstream your ideas!
+
+If you spot something that can be improved in this template, or if you want to
+suggest adding a notebook to the base materials, feel free to reach out! You can:
+
+- [Create an issue](https://github.com/napari/napari-workshop-template/issues/new)
+  with suggestions for improvement;
+- [Submit a Pull Request](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to the workshop template repository with your suggested changes;
+- [Reach out on Zulip chat](https://napari.zulipchat.com/) to tell us about your workshop and give feedback on the template or napari itself;
+- Add your workshop materials (including video, if available) to [the Workshops page in the napari documentation website](https://napari.org/stable/further-resources/napari-workshops.html).