Upstream 2024e

.codespell-ignore

@@ -0,0 +1,6 @@
+Fram
+dropse
+figurestyle
+hist
+namd
+rouge

.github/workflows/test_and_build.yml

@@ -6,17 +6,13 @@ on:
   push:
 
 jobs:
-  spellcheck:
+  lint_common_files:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.9'
       - name: Install codespell
         run: |
-          python3 -m pip install codespell
+          sudo apt-get install codespell
       - name: Check spelling
         run: |
           make spellcheck
@@ -35,13 +31,25 @@ jobs:
       - name: Check prose
         run: |
           proselint **/*.md
+      - name: Check top-level Markdown syntax
+        uses: DavidAnson/markdownlint-cli2-action@v9
+      - name: Check episode Markdown syntax
+        uses: DavidAnson/markdownlint-cli2-action@v9
+        with:
+          globs: _episodes/*.md
+      - name: Check extra Markdown syntax
+        uses: DavidAnson/markdownlint-cli2-action@v9
+        with:
+          globs: _extras/*.md
+
   check_lesson_and_build_default:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '2.7'
+          ruby-version: '3.0.4'
+          bundler-cache: true
       - name: Install basic requirements
         run: |
           # Need this library for nokogiri
@@ -50,9 +58,6 @@ jobs:
           bundle config set path '.vendor/bundle'
           bundle config build.nokogiri --use-system-libraries
           bundle install
-      - name: "Lint episode markdown"
-        run: |
-          find _episodes -name \*.md -exec bundle exec mdl -r MD001,MD003,MD005,MD006,MD007,MD008,MD009,MD010,MD011,MD012,MD015,MD016,MD017,MD018,MD019,MD020,MD021,MD022,MD023,MD025,MD035,MD036,MD037,MD038,MD039,MD046 {} \;
       - name: "Check lesson for warnings"
         run: |
           make lesson-check-all
@@ -73,7 +78,8 @@ jobs:
       - uses: actions/checkout@v2
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '2.7'
+          ruby-version: '3.0.4'
+          bundler-cache: true
       - name: Install basic requirements
         run: |
           # Need this library for nokogiri
@@ -85,6 +91,7 @@ jobs:
       - name: Check build ${{matrix.HPC_JEKYLL_CONFIG}}
         run: |
           make --always-make site HPC_JEKYLL_CONFIG=_includes/snippets_library/${{matrix.HPC_JEKYLL_CONFIG}}/_config_options.yml
-      - name: "Lint snippet markdown"
-        run: |
-          find _includes/snippets_library/${{matrix.HPC_JEKYLL_CONFIG}} -name \*.snip -exec bundle exec mdl -r MD001,MD003,MD005,MD006,MD007,MD008,MD009,MD010,MD011,MD012,MD015,MD016,MD017,MD018,MD019,MD020,MD021,MD022,MD023,MD025,MD035,MD036,MD037,MD038,MD039,MD046 {} \;
+      - name: Lint snippet markdown
+        uses: DavidAnson/markdownlint-cli2-action@v9
+        with:
+          globs: _includes/snippets_library/${{matrix.HPC_JEKYLL_CONFIG}}/**/*.snip

.markdownlint-cli2.yaml

@@ -0,0 +1,73 @@
+# markdownlint-cli2:
+# - Example: <https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml>
+# - Rules:   <https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases>
+---
+config:
+  MD001: false  # heading-increment
+  MD002: false  # mdl rule undefined
+  MD003: true   # heading-style
+  MD004: true   # ul-style
+  MD005: true   # list-indent
+  MD006: false  # mdl rule undefined
+  MD007: true   # ul-indent
+  MD008: false  # mdl rule undefined
+  MD009: true   # no-trailing-spaces
+  MD010: true   # no-hard-tabs
+  MD011: true   # no-reversed-links
+  MD012: true   # no-multiple-blanks
+  MD013: false  # line-length
+  MD014: false  # commands-show-output
+  MD015: false  # mdl rule undefined
+  MD016: false  # mdl rule undefined
+  MD017: false  # mdl rule undefined
+  MD018: true   # no-missing-space-atx
+  MD019: true   # no-multiple-space-atx
+  MD020: true   # no-missing-space-closed-atx
+  MD021: true   # no-multiple-space-closed-atx
+  MD022: true   # blanks-around-headings
+  MD023: true   # heading-start-left
+  MD024: false  # no-duplicate-heading
+  MD025: true   # single-h1
+  MD026: false  # no-trailing-punctuation
+  MD027: false  # no-multiple-space-blockquote
+  MD028: false  # no-blanks-blockquote
+  MD029: true   # ol-prefix
+  MD030: true   # list-marker-space
+  MD031: false  # blanks-around-fences
+  MD032: true   # blanks-around-lists
+  MD033: false  # no-inline-html
+  MD034: true   # no-bare-urls
+  MD035: true   # hr-style
+  MD036: true   # no-emphasis-as-heading
+  MD037: true   # no-space-in-emphasis
+  MD038: true   # no-space-in-code
+  MD039: true   # no-space-in-links
+  MD040: false  # fenced-code-language
+  MD041: false  # first-line-h1
+  MD042: true   # no-empty-links
+  MD043: false  # required-headings
+  MD044: true   # proper-names
+  MD045: true   # no-alt-text
+  MD046: true   # code-block-style
+  MD047: true   # single-trailing-newline
+  MD048: true   # code-fence-style
+  MD049: false  # emphasis-style
+  MD050: false  # strong-style
+  MD051: true   # link-fragments
+  MD052: true   # reference-links-images
+  MD053: false  # link-image-reference-definitions
+  MD054: false  # link-image-style
+  MD055: true   # table-pipe-style
+  MD056: true   # table-column-count
+
+ignores:
+  - .vendor
+  - .bundle
+  - _extras/figures.md  # really HTML
+  - _includes/links.md  # just a list of links
+  - "**/*.html"
+  - "**/*.sh"
+  - "**/*.yaml"
+  - "**/*.yml"
+
+# noProgress: true

CONTRIBUTING.md

@@ -130,4 +130,3 @@ which everyone is welcome to join. You can also [reach us by email][email].
 [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry
 [swc-lessons]: https://software-carpentry.org/lessons/
 [swc-site]: https://software-carpentry.org/
-

Gemfile

@@ -1,5 +1,19 @@
-source "https://rubygems.org"
-gem "github-pages", group: :jekyll_plugins
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Synchronize with https://pages.github.com/versions
+ruby '3.0.4'
+
+gem 'github-pages', group: :jekyll_plugins
+
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.0.0')
+  gem 'webrick', '>= 1.6.1'
+end
+
 gem "kramdown-parser-gfm"
+
 gem "mdl"
 gem "webrick"

LICENSE.md

@@ -1,9 +1,7 @@
 ---
-title: "Licenses"
+title: "License: CC BY 4.0"
 ---
 
-# CC BY 4.0
-
 ## Instructional Material
 
 All High Performance Computing Carpentry instructional material is

Makefile

@@ -155,7 +155,7 @@ lesson-fixme :
 
 ## spellcheck
 spellcheck:
-	codespell --skip="assets,*.svg,.vendor" --quiet-level=2  -L "dropse,figurestyle,hist,namd,rouge,ane"
+	codespell --skip=".bundle,.vendor,assets,*.svg" --quiet-level=2 --ignore-words=".codespell-ignore"
 
 ##
 ## IV. Auxililary (plumbing) commands

_config.yml

@@ -1,6 +1,17 @@
 #------------------------------------------------------------
 # NeSI: Mahuika + SLURM
 #------------------------------------------------------------
+
+# Cluster host and scheduler options: the defaults come from
+# the HPC Carpentry tutorial cluster, running Slurm. Other
+# options can be found in the library of snippets,
+# `_includes/snippets_library`. To use one, replace options
+# below with those in `_config_options.yml` from the
+# library. E.g, to customise for Cirrus at EPCC, running
+# Slurm, we could replace the options below with those from
+# 
+# _includes/snippets_library/EPCC_Cirrus_slurm/_config_options.yml
+# 
 # If your cluster is not represented in the library, please
 # copy an existing folder, rename it, and customize for your
 # installation. Remember to keep the leading slash on the
@@ -9,19 +20,22 @@
 snippets: "/snippets_library/NeSI_Mahuika_slurm"
 
 local:
-  prompt: "[user@laptop ~]$"
+  prompt: "[you@laptop:~]$"
   bash_shebang: "#!/usr/bin/env bash"
 
 remote:
   name: "mahuika"
   login: "nesi.org.nz"
+  portal: ""
   host: "mahuika02"
   node: "mahuika02"
   location: "Greta Point Datacenter"
   homedir: "/home"
   user: "yourUsername"
   prompt: "[yourUsername@mahuika ~]$"
   bash_shebang: "#!/bin/bash -e"
+  module_python3: "Python"
+
 
 sched:
   name: "Slurm"
@@ -30,6 +44,7 @@ sched:
     options: ""
   queue:
     debug: "debug"
+    testing: ""
   status: "squeue"
   flag:
     user: "-u yourUsername"
@@ -83,7 +98,7 @@ episode_order:
 # "swc": Software Carpentry
 # "dc":  Data Carpentry
 # "lc":  Library Carpentry
-# "cp":  Carpentries (e.g., instructor traning)
+# "cp":  Carpentries (e.g., instructor training)
 carpentry: "incubator"
 
 # Overall title for pages.

_episodes/.11-connecting.md

@@ -300,7 +300,9 @@ See the [PuTTY documentation][putty-agent].
 ### Transfer Your Public Key
 
 {% if site.remote.portal %}
-Visit {{ site.remote.portal }} to upload your SSH public key.
+Visit [{{ site.remote.portal }}]({{ site.remote.portal }}) to upload your SSH
+public key. (Remember, it's the one ending in `.pub`!)
+
 {% else %}
 Use the **s**ecure **c**o**p**y tool to send your public key to the cluster.
 
@@ -406,6 +408,8 @@ the other files, or files like them: `.bashrc` is a shell configuration file,
 which you can edit with your preferences; and `.ssh` is a directory storing SSH
 keys and a record of authorized connections.
 
+{% unless site.remote.portal %}
+
 ### Install Your SSH Key
 
 > ## There May Be a Better Way
@@ -449,6 +453,7 @@ password for your SSH key.
 {{ site.local.prompt }} ssh {{ site.remote.user }}@{{ site.remote.login }}
 ```
 {: .language-bash}
+{% endunless %}
 
 {% include links.md %}
 

_episodes/04-modules.md

@@ -38,7 +38,7 @@ not found` error, for instance.
 Software versioning is another common issue. A team might depend on a certain
 package version for their research project - if the software version was to
 change (for instance, if a package was updated), it might affect their results.
-Having access to multiple software versions allow a set of researchers to
+Having access to multiple software versions allows a set of researchers to
 prevent software versioning issues from affecting their results.
 
 Dependencies are where a particular software package (or even a particular
@@ -107,7 +107,7 @@ self-contained description of a software package -- it contains the
 settings required to run a software package and, usually, encodes required
 dependencies on other software packages.
 
-There are a number environment module implementations commonly
+There are a number of different environment module implementations commonly
 used on HPC systems: the two most common are _TCL modules_ and _Lmod_. Both of
 these use similar syntax and the concepts are the same so learning to use one
 will allow you to use whichever is installed on the system you are using. In
@@ -191,7 +191,6 @@ Now lets try loading the R environment module, and try again.
 
 {% include {{ site.snippets }}/modules/module-load-r.snip %}
 
-
 > ## Tab Completion
 >
 > The module command also supports tab completion. You may find this the easiest way to find the right software.
@@ -200,9 +199,7 @@ Now lets try loading the R environment module, and try again.
 So, what just happened?
 
 To understand the output, first we need to understand the nature of the `$PATH`
-environment variable.
-
-`$PATH` is a special environment variable that controls
+environment variable. `$PATH` is a special environment variable that controls
 where a UNIX system looks for software. Specifically `$PATH` is a list of
 directories (separated by `:`) that the OS searches through for a command
 before giving up and telling us it can't find it. As with all environment