Skip to content

Commit

Permalink
Merge pull request #371 from carpentries-incubator/bielsnohr/june-202…
Browse files Browse the repository at this point in the history
…4-ukaea-updates

Updates and modifications from June 2024 run at UKAEA
  • Loading branch information
anenadic authored Oct 15, 2024
2 parents f7a3b8d + ae65764 commit 69f0b0c
Show file tree
Hide file tree
Showing 17 changed files with 237 additions and 123 deletions.
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ vendor/
.docker-vendor/
Gemfile.lock
tmp/
.venv/
venv/
.venv/
.*history
.tool-versions
.vscode/
.ruby-version
slides/*.ipynb
slides/*.html
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
1 change: 1 addition & 0 deletions _config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ extras_order:
- object-oriented-programming
- persistence
- databases
- vscode
- quiz
# Files and directories that are not to be copied.
exclude:
Expand Down
14 changes: 10 additions & 4 deletions _episodes/11-software-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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" }
> >
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions _episodes/23-continuous-integration-automated-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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 %}
Expand Down
22 changes: 22 additions & 0 deletions _extras/common-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]:https://github.com/ukaea-rse-training/python-intermediate-inflammation
Cloning into 'python-intermediate-inflammation'...
[email protected]: 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
Expand Down
16 changes: 16 additions & 0 deletions _extras/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand Down
35 changes: 30 additions & 5 deletions _extras/vscode.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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}

Expand All @@ -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}

Expand Down Expand Up @@ -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
Binary file removed fig/git-feature-branch.png
Binary file not shown.
16 changes: 13 additions & 3 deletions slides/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 2 additions & 0 deletions slides/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
[tool.jupytext]
notebook_metadata_filter = "-kernelspec,-jupytext.text_representation.jupytext_version,rise,celltoolbar"
4 changes: 2 additions & 2 deletions slides/requirements.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
notebook < 7.0.0
rise
jupyter
jupyterlab_rise
jupytext
22 changes: 10 additions & 12 deletions slides/section_1_setting_up_environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand Down Expand Up @@ -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"} -->
Expand All @@ -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"} -->
Expand Down Expand Up @@ -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"} -->
Expand Down
9 changes: 2 additions & 7 deletions slides/section_2_ensuring_correctness.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand Down Expand Up @@ -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 -->

Expand Down
Loading

0 comments on commit 69f0b0c

Please sign in to comment.