Merge branch 'gh-pages' into patch-1

.gitignore

@@ -17,10 +17,11 @@ vendor/
 .docker-vendor/
 Gemfile.lock
 tmp/
-.venv/
 venv/
 .venv/
 .*history
 .tool-versions
 .vscode/
 .ruby-version
+slides/*.ipynb
+slides/*.html

README.md

@@ -1,11 +1,14 @@
+> [!NOTE]  
+> We are currently transitioning the lesson to the new Carpentries lesson format - please put your pull requests on hold and submit issues only.
+
 [![DOI](https://zenodo.org/badge/257930838.svg)](https://zenodo.org/badge/latestdoi/257930838)
 
 ## 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.
 
@@ -53,7 +56,7 @@ label ![pilot](https://shields.io/badge/-pilot-31E930).
 We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any
 questions, concerns, or experience any difficulties along the way.
 
-We'd like to ask you to familiarise yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
+We would like to ask you to familiarise yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at
 the [more detailed guidelines][lesson-example] on proper formatting, instructions on compiling and rendering the lesson locally, and 
 making any changes and adding new content or episodes.
 

_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:

_episodes/00-setting-the-scene.md

@@ -25,8 +25,8 @@ So, you have gained basic software development skills either by self-learning or
 e.g., a [novice Software Carpentry course][swc-lessons].
 You have been applying those skills for a while by writing code to help with your work
 and you feel comfortable developing code and troubleshooting problems.
-However, your software has now reached a point where there’s too much code to be kept in one script.
-Perhaps it's involving more researchers (developers) and users,
+However, your software has now reached a point where there is too much code to be kept in one script.
+Perhaps it is involving more researchers (developers) and users,
 and more collaborative development effort is needed to add new functionality
 while ensuring previous development efforts remain functional and maintainable.
 

_episodes/10-section1-intro.md

@@ -20,7 +20,7 @@ and introducing the project that we will be working on throughout the course.
 In order to build working (research) software efficiently
 and to do it in collaboration with others rather than in isolation,
 you will have to get comfortable with using a number of different tools interchangeably
-as they’ll make your life a lot easier.
+as they will make your life a lot easier.
 There are many options when it comes to deciding
 which software development tools to use for your daily tasks -
 we will use a few of them in this course that we believe make a difference.
@@ -124,6 +124,6 @@ Therefore, one should be aware of these guidelines
 and adhere to whatever the project you are working on has specified.
 In Python, we will be looking at a convention called PEP8.
 
-Let's get started with setting up our software development environment!
+Let us get started with setting up our software development environment!
 
 {% include links.md %}

_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" }
 > >
@@ -246,7 +251,7 @@ A novice will often make up the structure of their code as they go along.
 However, for more advanced software development,
 we need to plan and design this structure - called a *software architecture* - beforehand.
 
-Let's have a quick look into what a software architecture is
+Let us have a quick look into what a software architecture is
 and which architecture is used by our software project
 before we start adding more code to it.
 
@@ -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.

_episodes/12-virtual-environments.md

@@ -25,7 +25,7 @@ the `requirements.txt` file."
 ## Introduction
 So far we have cloned our software project from GitHub and inspected its contents and architecture a bit.
 We now want to run our code to see what it does -
-let's do that from the command line.
+let us do that from the command line.
 For the most part of the course we will run our code
 and interact with Git from the command line.
 While we will develop and debug our code using the PyCharm IDE
@@ -236,7 +236,7 @@ This will create the target directory for the virtual environment
 > and avoid issues that could prove difficult to trace and debug.
 {: .callout}
 
-For our project let's create a virtual environment called "venv".
+For our project let us create a virtual environment called "venv".
 First, ensure you are within the project root directory, then:
 
 ~~~
@@ -342,7 +342,7 @@ When you’re done working on your project, you can exit the environment with:
 ~~~
 {: .language-bash}
 
-If you've just done the `deactivate`,
+If you have just done the `deactivate`,
 ensure you reactivate the environment ready for the next part:
 
 ~~~
@@ -565,7 +565,13 @@ In the above command, we tell the command line two things:
 As we can see, the Python interpreter ran our script, which threw an error -
 `inflammation-analysis.py: error: the following arguments are required: infiles`.
 It looks like the script expects a list of input files to process,
-so this is expected behaviour since we don't supply any.
+so this is expected behaviour since we do not supply any.
 We will fix this error in a moment.
 
+## Optional exercises
+Checkout [this optional exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-try-out-different-virtual-environment-managers)
+to try out different virtual environment managers. 
+Or, [this exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-customize-the-command-line) 
+to customize the command line. 
+
 {% include links.md %}

_episodes/13-ides.md

@@ -80,10 +80,10 @@ and Microsoft's free [Visual Studio Code (VS Code)](https://code.visualstudio.co
 
 ## Using the PyCharm IDE
 
-Let's open our project in PyCharm now and familiarise ourselves with some commonly used features.
+Let us open our project in PyCharm now and familiarise ourselves with some commonly used features.
 
 ### Opening a Software Project
-If you don't have PyCharm running yet, start it up now.
+If you do not have PyCharm running yet, start it up now.
 You can skip the initial configuration steps which just go through
 selecting a theme and other aspects.
 You should be presented with a dialog box that asks you what you want to do,
@@ -156,7 +156,7 @@ and PyCharm is clever enough to understand it.
    so we can also use this environment for other projects if we wish.
 6. Select `OK` in the `Add Python Interpreter` window.
    Back in the `Preferences` window, you should select "Python 3.11 (python-intermediate-inflammation)"
-   or similar (that you've just added) from the `Project Interpreter` drop-down list.
+   or similar (that you have just added) from the `Project Interpreter` drop-down list.
 
 Note that a number of external libraries have magically appeared under the
 "Python 3.11 (python-intermediate-inflammation)" interpreter,
@@ -170,7 +170,7 @@ and has added these libraries effectively replicating our virtual environment in
 Also note that, although the names are not the same -
 this is one and the same virtual environment
 and changes done to it in PyCharm will propagate to the command line and vice versa.
-Let's see this in action through the following exercise.
+Let us see this in action through the following exercise.
 
 > ## Exercise: Compare External Libraries in the Command Line and PyCharm
 > Can you recall two places where information about our project's dependencies
@@ -314,15 +314,15 @@ You can also verify this from the command line by
 listing the `venv/lib/python3.11/site-packages` subdirectory.
 Note, however, that `requirements.txt` is not updated -
 as we mentioned earlier this is something you have to do manually.
-Let's do this as an exercise.
+Let us do this as an exercise.
 
 > ## Exercise: Update `requirements.txt` After Adding a New Dependency
 > Export the newly updated virtual environment into `requirements.txt` file.
 >
 >  
 >> ## Solution
->> Let's verify first that the newly installed library `pytest` is appearing in our virtual environment
->> but not in `requirements.txt`. First, let's check the list of installed packages:
+>> Let us verify first that the newly installed library `pytest` is appearing in our virtual environment
+>> but not in `requirements.txt`. First, let us check the list of installed packages:
 >> ~~~
 >> (venv) $ python3 -m pip list
 >> ~~~
@@ -412,7 +412,7 @@ and use on top of virtual environments.
    (i.e. the virtual environment and interpreter you configured earlier in this episode)
    in the `Python interpreter` field.
 5. You can give this run configuration a name at the top of the window if you like -
-   e.g. let's name it `inflammation analysis`.
+   e.g. let us name it `inflammation analysis`.
 6. You can optionally configure run parameters and environment variables in the same window -
    we do not need this at the moment.
 7. Select `Apply` to confirm these settings.
@@ -438,15 +438,15 @@ and use on top of virtual environments.
 Now you know how to configure and manipulate your environment in both tools
 (command line and PyCharm),
 which is a useful parallel to be aware of.
-Let's have a look at some other features afforded to us by PyCharm.
+Let us have a look at some other features afforded to us by PyCharm.
 
 ### Syntax Highlighting
 The first thing you may notice is that code is displayed using different colours.
 Syntax highlighting is a feature that displays source code terms
 in different colours and fonts according to the syntax category the highlighted term belongs to.
 It also makes syntax errors visually distinct.
 Highlighting does not affect the meaning of the code itself -
-it's intended only for humans to make reading code and finding errors easier.
+it is intended only for humans to make reading code and finding errors easier.
 
 ![Syntax Highlighting Functionality in PyCharm](../fig/pycharm-syntax-highlighting.png){: .image-with-shadow width="1000px" }
 
@@ -569,7 +569,12 @@ We will get back to this error shortly -
 for now, the good thing is that we managed to set up our project for development
 both from the command line and PyCharm and are getting the same outputs.
 Before we move on to fixing errors and writing more code,
-let's have a look at the last set of tools for collaborative code development
+Let us have a look at the last set of tools for collaborative code development
 which we will be using in this course - Git and GitHub.
 
+
+## Optional exercises
+Checkout [this optional exercise]({{ site.baseurl }}{% link _episodes/17-section1-optional-exercises.md %}#exercise-try-out-different-integrated-development-environments)
+to try out different IDEs and code editors.
+
 {% include links.md %}