Run tutorial in GitHub Codespaces (#259)

empa-scientific-it · Nov 26, 2024 · 6d6452e · 6d6452e
1 parent caf4594
commit 6d6452e
Show file tree

Hide file tree

Showing 5 changed files with 153 additions and 24 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,29 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python Tutorial",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "ghcr.io/empa-scientific-it/python-tutorial:latest",
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "pip3 install --user -r requirements.txt",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-python.python",
+				"ms-python.vscode-pylance",
+				"ms-python.debugpy",
+				"ms-toolsai.jupyter",
+				"ms-vsliveshare.vsliveshare"
+			]
+		}
+	}
+}
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,13 @@
+---
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+  - package-ecosystem: devcontainers
+    directory: /
+    schedule:
+      interval: weekly
diff --git a/README.md b/README.md
@@ -1,6 +1,9 @@
 # python-tutorial
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/empa-scientific-it/python-tutorial.git/main?labpath=index.ipynb) [![Build Docker container](https://github.com/empa-scientific-it/python-tutorial/actions/workflows/build-docker-image.yml/badge.svg)](https://github.com/empa-scientific-it/python-tutorial/actions/workflows/build-docker-image.yml)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/empa-scientific-it/python-tutorial.git/main?labpath=index.ipynb)
+[![Build Docker container](https://github.com/empa-scientific-it/python-tutorial/actions/workflows/build-docker-image.yml/badge.svg)](https://github.com/empa-scientific-it/python-tutorial/actions/workflows/build-docker-image.yml)
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=593234387)
 
 ## Run the tutorial on your computer
 

diff --git a/images/codespaces-jupyterlab.png b/images/codespaces-jupyterlab.png
diff --git a/intro.ipynb b/intro.ipynb
@@ -13,23 +13,25 @@
     "tags": []
    },
    "source": [
-    "# Table of contents\n",
-    "- [Welcome! 🐍](#Welcome!-🐍)\n",
+    "## Table of Contents\n",
+    "\n",
     "- [Timetable](#Timetable)\n",
     "- [How to interact](#How-to-interact)\n",
-    "- [Binder only](#Binder-only)\n",
+    "- [How to run the tutorial](#How-to-run-the-tutorial)\n",
+    "    - [With GitHub Codespaces](#With-GitHub-Codespaces)\n",
+    "    - [With Binder](#With-Binder)\n",
+    "    - [On your laptop](#On-your-laptop)\n",
     "- [How to use Jupyter Lab and the notebooks](#How-to-use-Jupyter-Lab-and-the-notebooks)\n",
-    "  - [Cells](#Cells)\n",
-    "  - [Store your progress](#Store-your-progress)\n",
-    "  - [Simple view](#Simple-view)\n",
-    "  - [File browser](#File-browser)\n",
-    "  - [Terminal](#Terminal)\n",
+    "    - [Cells](#Cells)\n",
+    "    - [Store your progress](#Store-your-progress)\n",
+    "    - [Simple view](#Simple-view)\n",
+    "    - [File browser](#File-browser)\n",
+    "    - [Terminal](#Terminal)\n",
     "- [Exercises 🌶️](#Exercises-🌶️)\n",
-    "  - [Exercise example](#Exercise-example)\n",
-    "  - [Exercise variables](#Exercise-variables)\n",
-    "  - [Exercise difficulty](#Exercise-difficulty)\n",
-    "- [Hands-on sessions](#Hands-on-sessions)\n",
-    "- [Let's get started! 🐍](#Let's-get-started!-🐍)"
+    "    - [Exercise example](#Exercise-example)\n",
+    "    - [Exercise variables](#Exercise-variables)\n",
+    "    - [Exercise difficulty](#Exercise-difficulty)\n",
+    "- [Hands-on sessions](#Hands-on-sessions)"
    ]
   },
   {
@@ -96,13 +98,59 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Binder only\n",
+    "# How to run the tutorial\n",
+    "\n",
+    "We designed the tutorial as a hands-on workshop. You should try to write as much code as possible to practice the foundational concepts."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## With GitHub Codespaces\n",
+    "\n",
+    "GitHub Codespaces is a cloud-based development environment that allows developers to code directly within their web browser, through Visual Studio Code, or Jupyter Lab.\n",
+    "It provides a fully configured development environment, including the necessary tools, libraries, and dependencies, tailored to the specific needs of your project.\n",
+    "\n",
+    "We are going to show you in practice how to create a codespace and run the tutorial inside it, but here a step-by-step guide.\n",
+    "From the repository on GitHub:\n",
+    "\n",
+    "**(1) Sign in to GitHub:**\n",
     "\n",
-    "During the tutorial, we request participants to **exclusively** use [Binder](https://mybinder.org/).\n",
-    "Everyone has their own combination of operating systems and software.\n",
-    "Supporting all of them is a challenge, which also takes time away from the actual content of the tutorial.\n",
+    "- Ensure you are logged into your GitHub account.\n",
     "\n",
-    "Binder is a service that allows you to run Jupyter Notebooks in the cloud.\n",
+    "**(2) Open the Codespaces Tab:**\n",
+    "\n",
+    "- Once you are on the repository's main page, look for the \"Code\" button (usually green) near the top right of the page.\n",
+    "- Click on the \"Code\" button to reveal a dropdown menu.\n",
+    "- In the dropdown menu, you will see a \"Codespaces\" tab. Click on it.\n",
+    "\n",
+    "**(3) Create a New Codespace:**\n",
+    "\n",
+    "- In the \"Codespaces\" tab, you will see an option to create a new Codespace. Click on the \"New codespace\" button.\n",
+    "- GitHub will start setting up your Codespace. This process involves provisioning a virtual machine, cloning the repository, and setting up the development environment based on the repository's configuration files.\n",
+    "\n",
+    "**(4) Access Your Codespace:**\n",
+    "\n",
+    "- Once the setup is complete, you will be automatically redirected to your new Codespace. This environment will be accessible either through your web browser or through Visual Studio Code if you prefer a desktop application.\n",
+    "- You can now start coding, running, and debugging your application directly within this environment\n",
+    "\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "    <h4><b>Note</b></h4>\n",
+    "    We <b>strongly</b> suggest you to work with the tutorial material via Jupyter Lab because Visual Studio Code is not 100% compatible with all the notebooks' features.\n",
+    "    You can start Jupyter Lab in your Codespace from the \"Code\" button as shown in the following screenshot.\n",
+    "</div>\n",
+    "\n",
+    "<img src=\"images/codespaces-jupyterlab.png\" alt=\"Jupyter Lab in Codespaces\" width=\"600\"/>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## With Binder\n",
+    "\n",
+    "[Binder](https://mybinder.org/) is a service that allows you to run Jupyter Notebooks in the cloud.\n",
     "It's free and requires no installation.\n",
     "You can use it by clicking the `launch|binder` button on the main page of the [official repository on GitHub](https://github.com/empa-scientific-it/python-tutorial) of the tutorial.\n",
     "\n",
@@ -115,12 +163,24 @@
     "\n",
     "\n",
     "<div class=\"alert alert-block alert-warning\">\n",
-    "<b>Warning:</b> Binder is free, so it provides limited resources.\n",
+    "    <h4><b>Warning</b></h4>\n",
+    "    Binder is free, so it provides limited resources.\n",
     "After 10 minutes of inactivity, your Binder instance will be shut down.\n",
     "You will lose all your work.\n",
     "To avoid this, please save your work regularly.\n",
     "See more about saving later in this notebook.\n",
-    "</div>\n"
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## On your laptop\n",
+    "\n",
+    "You can also run the tutorial locally, on your laptop.\n",
+    "We warmly suggest you to choose this route as a last resort since it might take some time to properly install/configure all the prerequisites.\n",
+    "Please, refer to the [README](https://github.com/empa-scientific-it/python-tutorial/blob/main/README.md#run-the-tutorial-on-your-computer) for detailed instructions.\n"
    ]
   },
   {
@@ -192,7 +252,29 @@
     "## Store your progress\n",
     "\n",
     "While working on the notebooks, you will probably want to save your progress.\n",
-    "Since Binder runs in the cloud, you cannot just press `Ctrl+S` to save your work - the notebook will be stored on the server, which is not accessible to you.\n",
+    "How to do it depends on where you are running the tutorial.\n",
+    "\n",
+    "### In GitHub Codespaces\n",
+    "\n",
+    "With either Jupyter Lab or Visual Studio Code, saving your work in your Codespace works the same as if you were working on your laptop.\n",
+    "\n",
+    "In Jupyter Lab, you can use the \"File\" menu (`File > Save Notebook`) or simply use the shortcuts `Ctrl+S` (Windows/Linux) or `Cmd+S` (macOS).\n",
+    "\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "    <h4><b>Note</b></h4>\n",
+    "    <h5>Codespace resources</h5>\n",
+    "    Running a GitHub Codespace consume resources (storage and compute). GitHub will provide each Free plan account 120 core hours, or 60 hours of run time for a 2 core codespace, plus 15 GB of storage to use <b>each month</b>. If you exceed these quotas, you are going to be <a href=\"https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces\">billed</a> for the extra resources.\n",
+    "</div>\n",
+    "\n",
+    "<div class=\"alert alert-block alert-warning\">\n",
+    "    <h4><b>Warning</b></h4>\n",
+    "    <h5>Automatic deletion</h5>\n",
+    "    By default, a Codespace that has been stopped for <b>more than 30 days</b> is automatically deleted by GitHub. Make sure you save your work <b>outside</b> your Codespace before stopping it. If you need help, don't hesitate to ask during the tutorial.\n",
+    "</div>\n",
+    "\n",
+    "### In Binder\n",
+    "\n",
+    "With Binder you cannot just press `Ctrl+S` (or `Cmd+S`) to save your work - the notebook will be stored on the server, which is not accessible to you.\n",
     "A better solution is to use those buttons in the toolbar:\n",
     "\n",
     "<img src=\"images/save_binder.png\" alt=\"Save\"/>\n",
@@ -227,7 +309,8 @@
    "metadata": {},
    "source": [
     "<div class=\"alert alert-block alert-warning\">\n",
-    "<b>Warning:</b> The procedure described above will only work if you don't close the browser window.\n",
+    "    <h4><b>Warning</b></h4>\n",
+    "    The procedure described above will only work if you don't close the browser window.\n",
     "If you close your browser, it would be better to download the notebook to your computer.\n",
     "To do so, go to <code>File</code> -> <code>Download</code>.\n",
     "</div>"
@@ -387,7 +470,8 @@
     "After 3 failed attempts, a proposed solution will be revealed.\n",
     "\n",
     "<div class=\"alert alert-block alert-warning\">\n",
-    "<b>Important:</b> The input arguments or the expected results of an exercise can be <strong>quite long</strong>. The output of the tests might be a bit difficult to navigate. If you need help with that, just <strong>ask</strong> 😉.\n",
+    "    <h4><b>Note</b></h4>\n",
+    "    The input arguments or the expected results of an exercise can be <strong>quite long</strong>. The output of the tests might be a bit difficult to navigate. If you need help with that, just <strong>ask</strong> 😉.\n",
     "</div>"
    ]
   },