Merge remote-tracking branch 'origin/main' into add-jupyter-esmvalcoreapi-tutorial

Author: flicj191

.github/workflows/build-check-tutorial-site.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: "ubuntu-latest"
     steps:
     - uses: actions/checkout@v2
     - name: Setup Ruby

Gemfile

@@ -7,4 +7,10 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 # Synchronize with https://pages.github.com/versions
 ruby '>=2.5.3'
 
-gem 'github-pages', group: :jekyll_plugins
+#  github-pages conflics with jekyll+liquid, but the site
+#  builds well locally; github-pages gem is semi-deprecated
+#  and should not be used as gem anymore, instead use via Actions
+#  gem 'github-pages', group: :jekyll_plugins
+gem 'jekyll', '~> 4.3'
+gem 'csv'
+gem 'bigdecimal'

Makefile

@@ -7,7 +7,7 @@ export SHELL = /bin/bash
 # Settings
 MAKEFILES=Makefile $(wildcard *.mk)
 JEKYLL_VERSION=3.8.5
-JEKYLL=bundle install --path .vendor/bundle && bundle update && bundle exec jekyll
+JEKYLL=bundle install && bundle update --all && bundle exec jekyll
 PARSER=bin/markdown_ast.rb
 DST=_site
 

_episodes/00-introduction.md

@@ -2,14 +2,14 @@
 title: "Introduction"
 teaching: 5
 exercises: 10
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.14.0
 
 questions:
 - What is ESMValTool?
 - Who are the people behind ESMValTool?
 
 objectives:
-- Familiarize with ESMValTool
+- Familiarization with ESMValTool
 - Synchronize expectations
 
 keypoints:
@@ -66,8 +66,8 @@ documentation:
     - lastname_firstname
 
 datasets:
-  - {dataset: HadGEM2-ES, project: CMIP5, exp: historical, mip: Amon, 
-     ensemble: r1i1p1, start_year: 1960, end_year: 2005}
+  - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical, mip: Amon, 
+     ensemble: r1i1p1f2, start_year: 1960, end_year: 2005}
 
 preprocessors:
   global_mean:
@@ -84,7 +84,7 @@ diagnostics:
     scripts: hockeystick.py
 ```
 
-> ## Understanding the different section of the recipe
+> ## Understanding the different sections of the recipe
 >
 > Try to figure out the meaning of the different dataset keys. Hint: they can
 > be found in the documentation of ESMValTool.
@@ -106,7 +106,7 @@ results.
 > ## Explore the available recipes
 >
 > Go to the [ESMValTool Documentation webpage](https://docs.esmvaltool.org/) and
-> explore the `Available recipes` section. Which recipe(s) would you like to
+> explore the `Recipes` section in the sidebar. Which recipe(s) would you like to
 > try?
 {: .challenge}
 
@@ -123,8 +123,8 @@ some of the most important pages.
 > the GitHub page of our 'organization'. Have a look around. How many collaborators are
 > there? Do you know any of them?
 >
-> Near the top of the page there are 2 pinned repositories: ESMValTool and
-> ESMValCore. Visit each of the repositories. How many people have contributed
+> Near the top of the page there are 3 pinned repositories: ESMValTool, 
+> ESMValCore and Community. Visit each of the repositories. How many people have contributed
 > to each of them? Can you also find out how many people have contributed to
 > this tutorial?
 {: .challenge}

_episodes/01-quickstart.md

@@ -2,7 +2,7 @@
 title: "Quickstart guide"
 teaching: 2
 exercises: 8
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.14.0
 
 questions:
 
@@ -27,7 +27,7 @@ keypoints:
   see the [Installation][lesson-installation]
   episode for more details and use `esmvaltool --help` to check the ESMValTool 
   environment"
-- "Use `esmvaltool config get_config_user` to create the ESMValTool user 
+- "Use `esmvaltool config copy defaults/config-user.yml` to create the ESMValTool user 
   configuration file"
 - "Use `esmvaltool run <recipe>.yml` to run a recipe"
 ---
@@ -49,7 +49,13 @@ keypoints:
 > 
 > - Load the ESMValTool environment by following the instructions at
 >   [ESMValTool: Pre-installed versions on HPC clusters / other 
->   servers][activate-environment].
+>   servers][activate-environment]. This will typically involving loading a module
+>   like so:
+>
+>     ~~~
+>     module load esmvaltool
+>     ~~~
+>     {: .language-bash}
 >
 > - Check the ESMValTool environment by accessing the help for ESMValTool:
 >
@@ -62,10 +68,10 @@ keypoints:
 > ## How do I configure ESMValTool?
 >
 > - Create the ESMValTool user configuration file (the file is written by 
->   default to `~/.esmvaltool/config-user.yml`):
+>   default to `~/.config/esmvaltool/config-user.yml`):
 >
 >     ~~~
->     esmvaltool config get_config_user
+>     esmvaltool config copy defaults/config-user.yml
 >     ~~~
 >     {: .language-bash}
 > 
@@ -107,4 +113,4 @@ keypoints:
 >   [Running your first recipe][lesson-recipe] episode in this tutorial.
 {: .challenge}
 
-{% include links.md %}
+{% include links.md %}

_episodes/02-installation.md

@@ -2,7 +2,7 @@
 title: "Installation"
 teaching: 10
 exercises: 10
-compatibility: ESMValTool v2.10.0
+compatibility: ESMValTool v2.14.0
 questions:
 - "What are the prerequisites for installing ESMValTool?"
 - "How do I confirm that the installation was successful?"
@@ -67,31 +67,36 @@ ESMValTool is distributed using [Mamba](https://mamba.readthedocs.io/en/latest/i
 To install mamba on ``Linux`` or ``MacOSX``, follow the  instructions below:
 
 1.  Please download the installation file for the latest Mamba version 
-[here](https://github.com/conda-forge/miniforge#mambaforge).
+for Linux 
+[here](https://github.com/conda-forge/miniforge/releases/latest/download/
+Miniforge3-Linux-x86_64.sh)
+or for MacOSX 
+[here](https://github.com/conda-forge/miniforge/releases/latest/download/
+Miniforge3-MacOSX-x86_64.sh).
 
 2.  Next, run the installer from the place where you downloaded it:
 
     On ``Linux``:
 
     ```bash
-    bash Mambaforge-Linux-x86_64.sh
+    bash Miniforge3-Linux-x86_64.sh
     ```
 
     On ``MacOSX``:
 
     ```bash
-    bash Mambaforge-MacOSX-x86_64.sh
+    bash Miniforge3-MacOSX-x86_64.sh
     ```
 
 3.  Follow the instructions in the installer. The defaults should normally
     suffice.
 
 4.  You will need to restart your terminal for the changes to have effect.
 
-5.  We recommend updating mamba before the esmvaltool installation. To do so, run:
+5.  We recommend updating mamba and conda before the esmvaltool installation. To do so, run:
 
     ```bash
-    mamba update --name base mamba
+    mamba update --name base mamba conda
     ```
 
 6.  Verify you have a working mamba installation by: 
@@ -100,7 +105,7 @@ To install mamba on ``Linux`` or ``MacOSX``, follow the  instructions below:
     which mamba
     ```
 
-    This should show the path to your mamba executable, e.g. `~/mambaforge/bin/mamba`.
+    This should show the path to your mamba executable, e.g. `~/miniforge3/bin/mamba`.
 
 For more information about installing mamba,
 see [the mamba installation documentation](https://docs.esmvaltool.org/en
@@ -109,7 +114,7 @@ see [the mamba installation documentation](https://docs.esmvaltool.org/en
 ### Install the ESMValTool package
 
 The ESMValTool package contains diagnostics scripts in four languages: R,
-Python, Julia and NCL. This introduces a lot of dependencies, and therefore the
+Python and NCL. This introduces a lot of dependencies, and therefore the
 installation can take quite long. It is, however, possible to install
 'subpackages' for each of the languages. The following (sub)packages are
 available:
@@ -126,7 +131,7 @@ ESMValTool package, run
 mamba create --name esmvaltool esmvaltool 
 ```
 
-On MacOSX ESMValTool functionalities in Julia, NCL, and R are not supported. To install
+On MacOSX ESMValTool functionalities in  NCL, and R are not supported. To install
 a Mamba environment on MacOSX, please refer to specific [information](https://
 docs.esmvaltool.org/en/latest/quickstart/installation.html#installation-on-
 macosx).
@@ -146,59 +151,13 @@ installed in it.
 >
 {: .callout}
 
-### Install Julia
-
-Some ESMValTool diagnostics are written in the Julia programming language.
-If you want a full installation of ESMValTool including Julia diagnostics, you need
-to make sure Julia is installed before installing ESMValTool.
-
-In this tutorial, we will not use Julia, but for reference, we have listed the steps
-to install Julia below.
-Complete instructions for installing Julia can be found on the [Julia
-installation page](https://julialang.org/downloads/platform/#linux_and_freebsd).
-
-> ## Julia installation instructions
->
-> First, open a bash terminal and activate the newly created `esmvaltool` environment.
->
-> ```bash
-> conda activate esmvaltool
-> ```
->
-> Next, to install Julia via `mamba`, you can use the following command:
->
-> ```bash
-> mamba install julia
-> ```
-> 
-> To check that the Julia executable can be found, run
->
-> ```bash
-> which julia
-> ```
->
-> to display the path to the Julia executable, it should be
->
-> ```
-> ~/mambaforge/envs/esmvaltool/bin/julia
-> ```
-> {: .output}
->
-> To test that Julia is installed correctly, run
->
-> ```bash
-> julia
-> ```
->
-> to start the interactive Julia interpreter. Press `Ctrl+D` to exit.
-{: .solution}
 
 ### Test that the installation was successful
 
 To test that the installation was successful, run
 
 ```bash
-conda activate esmvaltool
+mamba activate esmvaltool
 ```
 
 to activate the conda environment called `esmvaltool`. In the shell prompt the
@@ -229,13 +188,13 @@ to display the command line help.
 > > {: .bash}
 > > The version of ESMValTool installed should be displayed on the screen as:
 > > ~~~
-> > ESMValCore: 2.10.0
-> > ESMValTool: 2.10.0
+> > ESMValCore: 2.14.0
+> > ESMValTool: 2.14.0
 > > ~~~
 > > {: .output}
 > Note that on HPC servers such as JASMIN, sometimes a more recent development 
 > version may be displayed for ESMValTool, for e.g. 
-> `ESMValTool: 2.9.0.dev4+g6948d5512`
+> `ESMValTool: 2.15.0.dev4+g74d7837f0`
 > {: .solution}
 {: .challenge}