Merge pull request #371 from carpentries-incubator/bielsnohr/june-2024-ukaea-updates

anenadic · web-flow · commit 69f0b0cdca3b · 2024-10-15T13:38:26.000+01:00
Updates and modifications from June 2024 run at UKAEA
diff --git a/.gitignore b/.gitignore
@@ -17,10 +17,11 @@ vendor/
 .docker-vendor/
 Gemfile.lock
 tmp/
-.venv/
 venv/
 .venv/
 .*history
 .tool-versions
 .vscode/
 .ruby-version
+slides/*.ipynb
+slides/*.html
diff --git a/README.md b/README.md
@@ -5,10 +5,10 @@
 
 ## Intermediate Research Software Development Skills (Python)
 
-This is an intermediate-level course in collaborative research software engineering and development skills, 
-using Python as an example language. 
-It teaches these skills in a way that mimics a typical software development 
-process working as a part of a team, 
+This is an intermediate-level course in collaborative research software engineering and development skills,
+using Python as an example language.
+It teaches these skills in a way that mimics a typical software development
+process working as a part of a team,
 starting from an [existing piece of software](https://github.com/carpentries-incubator/python-intermediate-inflammation).
 The lesson is developed using [The Carpentries](https://carpentries.org) Jekyll lesson template.
 
diff --git a/_config.yml b/_config.yml
@@ -100,6 +100,7 @@ extras_order:
   - object-oriented-programming
   - persistence
   - databases
+  - vscode
   - quiz
 # Files and directories that are not to be copied.
 exclude:
diff --git a/_episodes/11-software-project.md b/_episodes/11-software-project.md
@@ -20,6 +20,7 @@ patients’ inflammation data and performs basic statistical analysis using Pyth
 ---
 
 ## Patient Inflammation Study Project
+
 You have joined a software development team that has been working on the
 [patient inflammation study project](https://github.com/carpentries-incubator/python-intermediate-inflammation)
 developed in Python and stored on GitHub.
@@ -98,17 +99,21 @@ and then obtain a local copy of that project (from your GitHub) on your machine.
    ![View of your own fork of the software repository in GitHub](../fig/github-forked-repository-own.png){: .image-with-shadow width="900px" }
 
 > ## Exercise: Obtain the Software Project Locally
+>
 > Using the command line, clone the copied repository
 > from your GitHub account into the home directory on your computer using SSH.
 > Which command(s) would you use to get a detailed list of contents of the directory you have just cloned?
-> 
-> 
+>
+>
 > > ## Solution
 > > 1. Find the SSH URL of the software project repository to clone from your GitHub account.
 > > Make sure you do not clone the original repository but rather your own fork,
 > > as you should be able to push commits to it later on.
-> > Also make sure you select the **SSH** tab and not the **HTTPS** one -
-> > for this course, SSH is the preferred way of authenticating when sending your changes back to GitHub.
+> > Also make sure you select the **SSH** tab and not the **HTTPS** one.
+> > For this course, SSH is the preferred way of authenticating when sending your changes back to GitHub.
+> > If you have only authenticated through HTTPS in the past,
+> > please follow the guidance [at the top of this section](#downloading-our-software-project)
+> > to add an SSH key to your GitHub account.
 > >
 > > ![URL to clone the repository in GitHub](../fig/clone-repository.png){: .image-with-shadow width="800px" }
 > >
@@ -269,6 +274,7 @@ are bigger modules that contain several smaller sub-modules.
 Another example of modules are classes in object-oriented programming languages.
 
 > ## Programming Modules and Interfaces
+>
 > Although modules are self-contained and independent elements to a large extent
 > (they can depend on other modules),
 > there are well-defined ways of how they interact with one another.
diff --git a/_episodes/23-continuous-integration-automated-testing.md b/_episodes/23-continuous-integration-automated-testing.md
@@ -201,7 +201,7 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Set up Python 3.11
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.11"
 
@@ -382,7 +382,7 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         # Here we add the reference to the python-version matrix values
         python-version: {% raw %}${{ matrix.python-version }}{% endraw %}
diff --git a/_extras/common-issues.md b/_extras/common-issues.md
@@ -137,6 +137,28 @@ $ git config --global core.editor "nano -w"
 ~~~
 {: .language-bash}
 
+
+## SSH key authentication issues with Git Bash
+
+Git Bash uses its own SSH library by default, which may result in errors such as the one below 
+even after adding your SSH key correctly:
+
+~~~
+$ git clone git@github.com:https://github.com/ukaea-rse-training/python-intermediate-inflammation
+Cloning into 'python-intermediate-inflammation'...
+git@github.com: Permission denied (publickey).
+fatal: Could not read from remote repository.
+
+Please make sure you have the correct access rights
+and the repository exists.
+~~~
+
+The solution is to change the SSH library used by Git:
+
+~~~
+$ git config --global core.sshCommand C:/windows/System32/OpenSSH/ssh.exe
+~~~
+
 ## Python, `pip`, `venv` & Installing Packages Issues
 
 ### Issues With Numpy (and Potentially Other Packages) on New M1 Macs
diff --git a/_extras/guide.md b/_extras/guide.md
@@ -9,6 +9,7 @@ title: "Instructor Notes"
 
 
 ## Course Design
+
 The course follows a narrative around
 a software development team working on an existing software project
 that is analysing patients’ inflammation data
@@ -41,6 +42,7 @@ The course has been separated into 5 sections:
 Each section can be approximately delivered in a half-day but even better if you can allow 1 day per section.
 
 ## Course Delivery
+
 The course is intended primarily for self-learning
 but other modes of delivery have been used successfully
 (e.g. fully instructor-led code-along mode or mixing in elements of instructor-led with self-work).
@@ -87,7 +89,16 @@ to make sure everyone is in sync as much as possible and are working on similar
 This synchronisation becomes particularly important for later workshop stages
 when students start with group exercises.
 
+Although not explicitly endorsed,
+it is quite possible for learners to do the course using VS Code instead of PyCharm.
+There is a section for setting up VS Code in the [this adjacent extras page](../vscode).
+However, when progressing through the section [Integrated Software Development Environments](../13-ides),
+it can be a bit difficult for learners to pay attention to both pages.
+Therefore, some instructors have found it helpful to perform a demonstration on their own machines of how to use VS Code to achieve the same functionality as PyCharm.
+It is worthwhile preparing this in advance of the session.
+
 ### Helpers Roles and Responsibilities
+
 At the workshop, when using the "self-learning with helpers" delivery mode, everyone in the training team is a helper and 
 there are no instructors per se.
 You may have more experienced helpers delivering introductions to the workshop and sections.
@@ -110,8 +121,13 @@ Roles and responsibilities of helpers include:
 - Helping students get through the material
   but also being ready to answer questions on applying the material in learners’ domains,
   if possible
+- Monitoring the progress of students
+  - get up every now and then and do a walk around the room, look at stickies and have a peak at
+    computer screens (particularly if the session is running a bit behind)
+  - ask any learners that you might have helped previously how they are getting on
 
 ### Group Exercises
+
 Here is some advice on how best to sync and organise group exercises in later stages of the course.
 
 - For earlier workshop stages,
diff --git a/_extras/vscode.md b/_extras/vscode.md
@@ -18,12 +18,32 @@ in the VS Code sidebar:
 
 ![VS Code application window with the Extensions button highlighted](../fig/vs-code-extensions.png){: .image-with-shadow width="800px" }
 
-In the search box, type "python" and select the Intellisense Python extension by Microsoft, 
-then click the "Install" button to install the extension. You may be asked to reload the VS Code IDE for the changes 
-to take effect.
+In the search box, type "python" and select the Intellisense Python extension by Microsoft,
+then click the "Install" button to install the extension.
+You may be asked to reload the VS Code IDE for the changes to take effect.
 
 ![VS Code application with the list of extensions found by search term "python"](../fig/vs-code-python-extension.png){: .image-with-shadow width="800px" }
 
+### Using VS Code with Windows Subsystem for Linux
+
+If you are developing software on Windows,
+and particularly software that comes from or targets Unix or Linux systems,
+it can be advantageous to use [WSL (Windows Subsystem for Linux)][wsl].
+Although this course does not explicitly support WSL,
+we will provide some guidance here on how to best link up WSL with VS Code (if that is your use case).
+In your WSL terminal, navigate to the project folder for this course and execute the command:
+
+```bash
+code .
+```
+
+This should launch VS Code in a way that ensures it performs most operations within WSL.
+To do this, the [WSL - Remote extension][vscode-wsl-extension]
+for VS Code should automatically be installed.
+If this does not happen, please install the extension manually.
+You can also launch WSL sessions from VS Code itself using the
+[instructions on the extension page.][vscode-wsl-extension-launch-options]
+
 ## Using the VS Code IDE
 
 Let us open our software project in VS Code and familiarise ourselves with some commonly used features needed for this course.
@@ -85,7 +105,7 @@ For this course you will need to install `pytest`, `numpy` and `matplotlib`. Sta
 following:
 
 ~~~
-pip install numpy matplotlib pytest
+python3 -m pip install numpy matplotlib pytest
 ~~~
 {: .language-bash}
 
@@ -98,7 +118,7 @@ Pip will usually inform you via a warning if a newer version is available.
 You can upgrade pip by running the following from the terminal:
 
 ~~~
-pip install --upgrade pip
+python3 -m pip install --upgrade pip
 ~~~
 {: .language-bash}
 
@@ -175,3 +195,8 @@ When clicking on a test you will see two icons,
 the ordinary Run/Play icon, and a Run/Play icon with a bug.
 The latter allows you to run the tests in debug mode
 useful for obtaining further information as to why a failure has occurred - this will be covered in the main lesson material.
+
+
+[vscode-wsl-extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl
+[vscode-wsl-extension-launch-options]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl#commands
+[wsl]: https://learn.microsoft.com/en-us/windows/wsl/about
diff --git a/fig/git-feature-branch.png b/fig/git-feature-branch.png
diff --git a/slides/README.md b/slides/README.md
@@ -15,13 +15,23 @@ python3 -m venv .venv  # it is important to use the dot prefix if you are creati
 pip install -r slides/requirements.txt 
 # launch jupyter from the top level of this repo, **not** in the slide
 # directory or else the relative figure links will not work
-jupyter-notebook
-# navigate to the slide file and edit
+jupyter-notebook #  or `jupyter-lab`
+# navigate to the slide file, right click then select "open with > notebook".
 ```
 
+> Note: we have had mixed success using the RISE extension in both `jupyter-notebook` and `jupyter-lab`.
+> Try the other if one isn't working for you.
+> To use the old `jupyter-notebook`, put this in the `requirements.txt` file:
+>
+> ```requirements
+> notebook < 7.0.0
+> rise
+> jupytext
+> ```
+
 Use the RISE extension to Jupyter to view the slides.
 This allows you to enter the slideshow from the Jupyter notebook web interface.
-There should be a button with a histogram on the Jupyter notebook toolbar
+There should be a "projector screen" button on the Jupyter notebook toolbar next to the kernel name
 (you might need to go to the 'View' menu to get the toolbar to show).
 Click the button, or press `Alt-r` to launch the RISE presentation view.
 Use spacebar to advance slides. Presenter view with `t`.
diff --git a/slides/pyproject.toml b/slides/pyproject.toml
@@ -0,0 +1,2 @@
+[tool.jupytext]
+notebook_metadata_filter = "-kernelspec,-jupytext.text_representation.jupytext_version,rise,celltoolbar"
diff --git a/slides/requirements.txt b/slides/requirements.txt
@@ -1,3 +1,3 @@
-notebook < 7.0.0
-rise
+jupyter
+jupyterlab_rise
 jupytext
diff --git a/slides/section_1_setting_up_environment.md b/slides/section_1_setting_up_environment.md
@@ -2,16 +2,11 @@
 jupyter:
   celltoolbar: Slideshow
   jupytext:
-    notebook_metadata_filter: rise,celltoolbar
+    notebook_metadata_filter: -kernelspec,-jupytext.text_representation.jupytext_version,rise,celltoolbar
     text_representation:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.6
-  kernelspec:
-    display_name: Python 3 (ipykernel)
-    language: python
-    name: python3
   rise:
     theme: solarized
 ---
@@ -395,7 +390,6 @@ pip install -r requirements.txt  # great reason to have this file
 - Preference for Code Editors and IDEs is one of the more contentious and strongly felt topics among software developers, but the bottom line is that if a tool works for you and helps you be productive, then it is absolutely fine to use that tool
   - But again, for the practicalities of this course, the decision to support two editors, PyCharm and VSCode, has been made
   - If you are comfortable enough in another IDE or code editor to get the functionality demonstrated in the content below, then please feel free to use that tool here, but this is a disclaimer that we cannot promise to resolve any issues you have, and if these issues are holding the group up then we will need to move on
-  - For VSCode, please consult the "Extras" content of the course web page and find the analogous functionality described there; if you are having trouble getting something to work, please ask for help!
 <!-- #endregion -->
 
 <!-- #region slideshow={"slide_type": "subslide"} -->
@@ -405,10 +399,14 @@ Start from this heading and continue to the end of the page.
 <!-- #endregion -->
 
 <!-- #region slideshow={"slide_type": "notes"} -->
-- Send learners into breakout rooms to read through and try out content from "Using the PyCharm IDE" (~ 30mins, but could be less, so poll helpers after 20 minutes to get a status check from the rooms, or ask directly if in person)
-  - Remind to use status green check when done (or red x if having trouble)
-  - Encourage learners to try out the features that are being discussed and do not worry about making modifications to their code since it is under version control it will be easy to reset any changes
-  - Reinforce that we Will not be using the version control interface of PyCharm, but it is a perfectly useable feature, and again this comes down to preference
+- Before launching into this exercise, you should poll how many students are using each editor
+  - If the majority are using VS Code, consider doing a demo of all the features listed for PyCharm
+    using your own VS Code editor
+  - Otherwise, send learners off to read through and try out content from "Using the PyCharm IDE" (~ 30mins, but could be less, so poll after 20 minutes to get a status check, or ask directly if in person)
+    - For VSCode users, remind them to consult the "Extras" content of the course web page and find the analogous functionality described there; if you are having trouble getting something to work, please ask for help!
+    - Remind to use status green check when done (or red x if having trouble)
+    - Encourage learners to try out the features that are being discussed and don't worry about making modifications to their code since it is under version control it will be easy to reset any changes
+    - Reinforce that we won't be using the version control interface of PyCharm, but it is a perfectly useable feature, and again this comes down to preference
 <!-- #endregion -->
 
 <!-- #region slideshow={"slide_type": "slide"} -->
@@ -451,7 +449,7 @@ Start from this heading and go until the "Git Branches" heading.
 <!-- #region slideshow={"slide_type": "subslide"} -->
 ### Git Branches
 
-<center><img src="../fig/git-feature-branch.png"></center>
+<center><img src="../fig/git-feature-branch.svg"></center>
 <!-- #endregion -->
 
 <!-- #region slideshow={"slide_type": "notes"} -->
diff --git a/slides/section_2_ensuring_correctness.md b/slides/section_2_ensuring_correctness.md
@@ -2,16 +2,11 @@
 jupyter:
   celltoolbar: Slideshow
   jupytext:
-    notebook_metadata_filter: rise,celltoolbar
+    notebook_metadata_filter: -kernelspec,-jupytext.text_representation.jupytext_version,rise,celltoolbar
     text_representation:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.6
-  kernelspec:
-    display_name: Python 3 (ipykernel)
-    language: python
-    name: python3
   rise:
     theme: solarized
 ---
@@ -204,7 +199,7 @@ Follow along from this section heading to the bottom of the page.
 
 <!-- #region slideshow={"slide_type": "notes"} -->
 - split learners into breakout rooms (~50 mins although likely less, so take a status check early) starting from this section heading and going to the end of the page
-  - if learners are using different editors, then encourage them to try and replicate the techique of debugging that is explained here
+  - if learners are using different editors, then encourage them to try and replicate the technique of debugging that is explained here
 - status check
 <!-- #endregion -->
 
diff --git a/slides/section_3_software_dev_process.md b/slides/section_3_software_dev_process.md
diff --git a/slides/section_4_collaborative_soft_dev.md b/slides/section_4_collaborative_soft_dev.md
diff --git a/slides/section_5_managing_software.md b/slides/section_5_managing_software.md
