Merge pull request #157 from FAIR2-for-research-software/ns-rse/146-move-conda-setup

ns-rse · web-flow · commit efe103310d4b · 2025-05-23T17:24:47.000+01:00
diff --git a/config.yaml b/config.yaml
@@ -60,9 +60,9 @@ contact: 'n.shephard@sheffield.ac.uk' # FIXME
 # Order of episodes in your lesson
 episodes:
 - introduction.md
+- git_hygiene.md
 - branching.md
 - diverging_branches.md
-- git_hygiene.md
 - hooks.md
 - continuous_integration.md
 # - reviewing.md
diff --git a/episodes/hooks.md b/episodes/hooks.md
@@ -229,6 +229,16 @@ exec git pull
 
 ## Pre-Commit
 
+::::::::::::::::::::::::::::::::::::: callout
+
+## Extra Setup
+
+This section requires you to either install `pre-commit` at the system level or setup a Virtual Environment.
+
+Instructions on doing so can be found at the bottom of the [document](hooks.md#installing_pre-commit).
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
 Pre-commit hooks that run before commits are made are _really_ useful to the extent that they require special discussion
 and will be the focus of the remainder of this episode. Why are they so useful? It's because they shorten the feedback
 loop of changes that need to be made when checking and linting code.
@@ -254,7 +264,7 @@ hook that resides at `.git/hooks/pre-commit`, although we will look at that file
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-### Why are Pre-Commit hooks so important?
+## Why are Pre-Commit hooks so important?
 
 You may be wondering why running hooks prior to commits is so important. The short answer, as we've already hear,  is
 that it reduces the feedback loop and speeds up the pace of development. The long answer is that it only really becomes
@@ -267,8 +277,9 @@ base, making some changes and committing them.
 other than Python. Many Linux systems have [pre-commit][pc] in their package management systems so if you are using
 Linux or OSX you can install these at the system level.
 
-However, for this course the setup instructions asked you to install [Miniconda][miniconda3] and we can install
-[`pre-commit`][pc] in a Conda environment to leverage it. The steps to do so are
+However, for this section of the course you should install [Miniconda][miniconda3] so we can install
+[`pre-commit`][pc] in a Conda environment to leverage it. There are instructions at the bottom of this page on how to
+install Miniconda. Once you have done so you can proceed with creating a conda environment. The steps to do so are
 
 1. Create a Conda environment called `python-maths` with `conda create -n python-maths python=3.11`
 2. Activate the newly created `python-maths` environment.
@@ -349,29 +360,6 @@ Proceed ([y]/n)?
 pre-commit installed at .git/hooks/pre-commit
 ```
 
-::::::::::::::::::::::::::::::::::::: callout
-
-## Install Pre-commit globally
-
-Examples of installing [pre-commit][pc] at the system level for different Linux systems or OSX. Note you will
-need to have `root` access to install packages on your Linux system.
-
-``` bash
-# Arch Linux
-❱ pacman -Syu pre-commit
-# Gentoo
-❱ emerge -av pre-commit
-# Debin/Ubuntu
-❱ apt-get install pre-commit
-# OSX Homebrew
-❱ brew install pre-commit
-```
-
-The advantage of this is that you will be able to `pre-commit install` in any repository without first having to
-activate a virtual environment.
-
-::::::::::::::::::::::::::::::::::::::::::::::::
-
 ::::::::::::::::::::::::::::::::::::: challenge
 
 ## Challenge 2 - Checking out the installed `pre-commit` hook
@@ -599,16 +587,18 @@ of the others that are defined.
 
 ## Solution 1 : What version of the `numpydoc` repo is configured
 
-Using [grep][grep] to search for the `numpydoc` string in the `.pre-commit-config.yaml` we can hone in on the `repo` and
-its associated `rev`.
+Using [grep][grep] to search for the [`numpydoc`][numpydoc] string in the `.pre-commit-config.yaml` we can hone in on
+the `repo` and its associated `rev`.
 
 ``` bash
 ❱ grep -A1 numpydoc .pre-commit-config.yaml  | grep -B1 rev
   - repo: https://github.com/numpy/numpydoc
     rev: v1.6.0
 ```
 
-We see that it is `v1.6.0` that is currently configured for `numpydoc`.
+We see that it is `v1.6.0` that is currently configured for [`numpydoc`][numpydoc].
+
+**NB** This hook ensures the docstrings of Python functions comply with thet [numpydocstyle][numpydocstyle] guide.
 
 :::::::::::::::::::::::::::::::::
 
@@ -784,64 +774,12 @@ The file should then be staged, committed and pushed.
 ## Adding repos
 
 The definitive [list][pc-hooks] of `pre-commit` repos is maintained on the official website. Each entry links to the
-GitHub repository and most contain in their `README.md` instructions on how to use the hooks.
-
-<!-- ::::::::::::::::::::::::::::::::::::: challenge -->
-
-<!-- ## Challenge 7: Add the `numpydoc` repo, exclude the `tests/` and `doc/` directories and run it against-->
-<!-- the code base -->
-
-<!-- The [numpydoc](https://github.com/numpy/numpydoc) repo defines hooks that check the Python docstrings -->
-<!-- conform to the [Numpydoc style guide](https://numpydoc.readthedocs.io/en/latest/format.html). Following the  -->
-<!-- instructions add the repo to the `.pre-commit-config.yaml` (on a new branch) -->
-
-<!-- :::::::::::::::::::::::: solution -->
-
-<!-- ## Solution -->
-
-<!-- Create a branch to undertake the work on. -->
-
-<!-- ``` bash -->
-<!-- ❱ git switch main -->
-<!-- ❱ git pull -->
-<!-- ❱ git switch -c ns-rse/pre-commit-numpydoc -->
-<!-- ``` -->
-
-<!-- The following should be added to your `.pre-commit-config.yaml` -->
-
-<!-- ``` yaml -->
-<!--    - repo: https://github.com/numpy/numpydoc -->
-<!--      rev: v1.6.0 -->
-<!--      hooks: -->
-<!--        - id: numpydoc-validation -->
-<!--          exclude: | -->
-<!--            (?x)( -->
-<!--                tests/| -->
-<!--                docs/ -->
-<!--            ) -->
-<!-- ``` -->
-
-<!-- Check that the code base passes the checks, correct any errors that are highlighted. -->
-
-<!-- ``` bash -->
-<!-- ❱ pre-commit run numpydoc --all-files -->
-<!-- ``` -->
-
-<!-- The file should then be staged, committed and pushed. -->
-
-<!-- ``` bash -->
-<!-- ❱ git add .pre-commit-config.yaml -->
-<!-- ❱ git commit -m "pre-commit : adds the numpydoc repo/hook" -->
-<!-- ❱ git push -->
-<!-- ``` -->
-
-<!-- ::::::::::::::::::::::::::::::::: -->
-
-<!-- :::::::::::::::::::::::::::::::::::::::::::::::: -->
+GitHub repository and most contain in their `README.md` instructions on how to use the hooks. Which you will want to use
+will depend very much on your project.
 
 ## Local repos
 
-Local repo are those that do not use hooks defined by others and are instead defined by the user. This comes in handy
+Local repos are those that do not use hooks defined by others and are instead defined by the user. This comes in handy
 when you want to run checks which have dependencies that are specific to the code such as running [pylint][pylint] which
 needs to import all the dependencies that are used or run a test suite.
 
@@ -978,12 +916,76 @@ the Pre-commit hooks as part of the Continuous Integration on GitHub which is th
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
+## Installing Pre-commit
+
+### Install Pre-commit globally
+
+Examples of installing [pre-commit][pc] at the system level for different Linux systems or OSX. Note you will
+need to have `root` access to install packages on your Linux system.
+
+``` bash
+# Arch Linux
+pacman -Syu pre-commit
+# Gentoo
+emerge -av pre-commit
+# Debin/Ubuntu
+apt-get install pre-commit
+# OSX Homebrew
+brew install pre-commit
+```
+
+The advantage of this is that you will be able to `pre-commit install` in any repository without first having to
+activate a virtual environment.
+
+### Virtual Environments
+
+The other option is to install `pre-commit` within a Python Virtual Environment. If you are already familiar with using
+these then you can simply `pip install pre-commit` and you are good to go, although note that `pre-commit` will need
+installing in _every_ new environment you create that you want to use it.
+
+If you are not familiar with Python Virtual Environments you can follow the instructions below to install and setup
+[miniconda3][miniconda3] or [miniforge3][miniforge3].
+
+::::::::::::::::::::::::::::::::::::: callout
+
+## Anaconda Licensing
+
+It is important to fully understand and adhere to the [Anaconda Licensing][anacondalicense] which permits
+the use of their software (including Miniconda) in educational and research environments _only_ if there is no
+commercial benefit. If the work you undertake involves commercial collaboration you should seek alternative solutions
+for virtual environments (e.g. [miniforge3][miniforge3] or [virtualenvwrapper][virtualenvwrapper]).
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+### Installing Miniconda/Miniforge3
+
+Please follow the instructions at [Installing Miniconda](https://docs.anaconda.com/free/miniconda/miniconda-install/)
+for your Operating System.
+
+Should you chose to use `miniforge3` the downloads and installation instructions for different operating systems can be
+found [here][miniforge3-install].
+
+### Creating A Virtual Environment
+
+You will have to create a virtual environment to undertake the course. If you have installed Miniconda as described
+above you open a terminal (Windows use the Git Bash Shell) and create a Virtual Environment called `git-collaboation`.
+
+``` bash
+conda create --name git-collab python=3.11
+conda activate git-collab
+```
+
+[anacondalicense]: https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research
 [bash]: https://www.gnu.org/software/bash/
 [black]: https://black.readthedocs.io/en/stable/index.html
 [gh]: https://github.com
 [gl]: https://gitlab.com
 [grep]: https://en.wikipedia.org/wiki/Grep
 [miniconda3]: https://docs.anaconda.com/free/miniconda/
+[miniforge3]: https://conda-forge.org/
+[miniforge3-install]: https://github.com/conda-forge/miniforge
+[numpydoc]: https://github.com/numpy/numpydoc
+[numpydocstyle]: https://numpydoc.readthedocs.io/en/latest/format.html
 [pc]: https://pre-commit.com
 [pc-ci]: https://pre-commit.ci
 [pc-hooks]: https://pre-commit.com/hooks
@@ -992,4 +994,5 @@ the Pre-commit hooks as part of the Continuous Integration on GitHub which is th
 [python]: https://python.org
 [pm]: https://github.com/ns-rse/python-maths
 [ruff]: https://astral.sh/ruff
+[virtualenvwrapper]: https://rse.shef.ac.uk/blog/2024-08-13-python-virtualenvwrapper/
 [yaml]: https://yaml.org
diff --git a/learners/setup.md b/learners/setup.md
@@ -27,7 +27,8 @@ Environment (IDE).
 
 For consistency across operating systems this course uses the Command Line Interface (CLI) to Git and instructions below
 will guide you through installation on different Operating Systems. The principles can be applied to any Git Porcelain
-(client) that you choose, including IDEs, although not all will support all of the functions introduced here (e.g. the
+(client) that you choose (e.g. [GitKraken][gitkraken]), including IDEs such as [VSCode][vscode], PyCharm,
+[RStudio][rstudio] and [Emacs][emacs], although not all will support all of the functions introduced here (e.g. the
 RStudio Git interface is very basic).
 
 :::::::::::::::::::::::::::::::::::::::::::::::::::
@@ -124,7 +125,9 @@ account][github_ssh].
 
 There is a detailed [article][ssh-keygen] on creating SSH keys under Linux and OSX that works with Git Bash too. It is
 recommended to use the newer [ed25519][ssh-ed25519] algorithm. In a terminal or Git Bash shell, you can do this using
-the following commands.
+the following commands. You will be prompted to enter your password twice, **make sure to enter a secure (i.e. long)
+password, password-less keys are insecure!**, make sure you remember what the password is (**Hint** use a password
+manager!).
 
 ```bash
 ssh-keygen -a 100 -t ed25519
@@ -174,72 +177,25 @@ Hi ns-rse! You've successfully authenticated, but GitHub does not provide shell
 If you do **not** see the above successful authentication message please get in touch **before** the course starts.
 :::::::::::::::::::::::::
 
-## Conda Environments
+::::::::::::::::::::::::::::::::::::: keypoints
 
-::::::::::::::::::::::::::::::::::::: callout
-
-## Anaconda Licensing
-
-It is important to fully understand and adhere to the [Anaconda Licensing][anacondalicense] which permits
-the use of their software (including Miniconda) in educational and research environments _only_ if there is no
-commercial benefit. If the work you undertake involves commercial collaboration you should seek alternative solutions
-for virtual environments (e.g. [miniforge3][miniforge3] or [virtualenvwrapper][virtualenvwrapper]).
+- You should have Git installed on your computer and opening a Terminal (or Git Bash Shell on Windows) you should be
+  able to type `git` and receive a summary of available commands.
+- You should have setup a GitHub account.
+- You should have created an SSH key and uploaded the public component to your GitHub Account (_Settings > SSH and GPG
+  Keys_).
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-::::::::::::::::::::::::::::::::::::::: discussion
-
-In order to teach this course we need some code that is version controlled and some tasks to complete. [Python][python]
-has been chosen as the language to fulfill that task. You do _not_ need to know Python in order to complete the course,
-the code you need to use is all provided and can be copy and pasted.
-
-However, you _do_ need what is known as a "_Virtual Environment_" setup to be able to install various programmes and run
-the checks that are part of this course. To that end you should install
-[Miniconda3][miniconda3]/[miniforge3][miniforge3] or another tool for managing Virtual Environments
-(e.g. [virtualenvwrapper][virtualenvwrapper]) on your system prior to attending the course.
-
-If you are already familiar with Python and Virtual Environments you can simply create a fresh virtual environment to
-use for the course.
-
-:::::::::::::::::::::::::::::::::::::::::::::::::::
-
-:::::::::::::::: solution
-
-### Installing Miniconda/Miniforge3
-
-Please follow the instructions at [Installing Miniconda](https://docs.anaconda.com/free/miniconda/miniconda-install/)
-for your Operating System.
-
-Should you chose to use `miniforge3` the downloads and installation instructions for different operating systems can be
-found [here][miniforge3-install].
-
-:::::::::::::::::::::::::
-
-:::::::::::::::: solution
-
-### Creating A Virtual Environment
-
-You will have to create a virtual environment to undertake the course. If you have installed Miniconda as described
-above you open a terminal (Windows use the Git Bash Shell) and create a Virtual Environment called `git-collaboation`.
-
-``` bash
-conda create --name git-collab python=3.11
-conda activate git-collab
-```
-
-:::::::::::::::::::::::::
-
-[anacondalicense]: https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research
+[emacs]: https://www.gnu.org/software/emacs/
 [gh]: https://github.com
 [git]: https://git-scm.com/
 [github_ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
+[gitkraken]: https://www.gitkraken.com/
 [gitMac]: https://git-scm.com/download/mac
 [gitWin]: https://git-scm.com/download/win
 [git4windows]: https://carpentries.github.io/workshop-template/install_instructions/#shell
-[miniconda3]: https://docs.anaconda.com/free/miniconda/
-[miniforge3]: https://conda-forge.org/
-[miniforge3-install]: https://github.com/conda-forge/miniforge
-[python]: https://python.org
+[rstudio]: https://posit.co/download/rstudio-desktop/
 [ssh-ed25519]: https://blog.g3rt.nl/upgrade-your-ssh-keys.html
 [ssh-keygen]: https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-openssh-on-macos-or-linux
-[virtualenvwrapper]: https://rse.shef.ac.uk/blog/2024-08-13-python-virtualenvwrapper/
+[vscode]: https://code.visualstudio.com/
