Move basic tutorial episodes from Carpentry to rst format

doc/sphinx/source/tutorials/episode_1_introduction.rst

@@ -0,0 +1,178 @@
+.. _epsiode_1:
+
+Introduction
+=====================
+
+.. admonition:: Overview
+   :class: note
+
+   .. grid:: 2
+      :gutter: 1
+      :margin: 3 3 0 5
+
+      .. grid-item-card:: Timings
+         :columns: 12
+
+         * Teaching: 5 min
+         * Exercises: 10 min
+
+      .. grid-item-card:: Questions
+
+         * What is ESMValTool?
+         * Who are the people behind ESMValTool?
+
+      .. grid-item-card:: Learning outcomes
+
+         * Familiarization with ESMValTool
+         * Synchronize expectations
+
+      .. grid-item-card:: Compatibility
+         :columns: 12
+
+         ESMValTool v2.15.0
+
+
+What is ESMValTool?
+-------------------
+
+This tutorial is a first introduction to ESMValTool. Before diving into the
+technical steps, let’s talk about what ESMValTool is all about.
+
+.. admonition:: What is ESMValTool?
+   :class: admonition-todo
+
+   What do you already know about or expect from ESMValTool?
+
+   .. dropdown:: ESMValTool is...
+      :color: secondary
+      :icon: eye
+
+      ESMValTool is many things, but in this tutorial we will focus on the
+      following traits:
+
+      * **A tool to analyse climate data**
+      * **A collection of diagnostics for reproducible climate science**
+      * **A community effort**
+
+A tool to analyse climate data
+------------------------------
+
+ESMValTool takes care of finding, opening, checking, fixing, concatenating,
+and preprocessing CMIP data and several other supported datasets.
+
+The central component of ESMValTool that we will see in this tutorial is the
+**recipe**. Any ESMValTool recipe is basically a set of instructions to
+reproduce a certain result. The basic structure of a recipe is as follows:
+
+* **Documentation** with relevant (citation) information
+* **Datasets** that should be analysed
+* **Preprocessor** steps that must be applied
+* **Diagnostic** scripts performing more specific evaluation steps
+
+An example recipe could look like this:
+
+.. code-block:: bash
+
+   documentation:
+   title: This is an example recipe.
+   description: Example recipe
+   authors:
+      - lastname_firstname
+
+   datasets:
+   - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical, mip: Amon,
+      ensemble: r1i1p1f2, start_year: 1960, end_year: 2005}
+
+   preprocessors:
+   global_mean:
+      area_statistics:
+         operator: mean
+
+   diagnostics:
+   hockeystick_plot:
+      description: plot of global mean temperature change
+      variables:
+         temperature:
+         short_name: tas
+         preprocessor: global_mean
+      scripts: hockeystick.py
+
+.. admonition:: Understanding the different sections of the recipe
+   :class: admonition-todo
+
+   Try to figure out the meaning of the different dataset keys. Hint: they can
+   be found in the documentation of ESMValTool.
+
+   .. dropdown:: Solution
+      :color: secondary
+      :icon: eye
+
+      The keys are explained in the ESMValCore documentation, in **The
+      recipe format** section under
+      :ref:`Overview <esmvalcore:recipe_overview>`.
+
+
+A collection of diagnostics for reproducible climate science
+------------------------------------------------------------
+
+More than a tool, ESMValTool is a collection of publicly available recipes and
+diagnostic scripts. This makes it possible to easily reproduce important
+results.
+
+.. admonition:: Explore the available recipes
+   :class: admonition-todo
+
+   Go to the :doc:`ESMValTool documentation </index>`
+   and explore the **Recipes** section in the sidebar. Which recipe(s) would
+   you like to try?
+
+A community effort
+------------------
+
+ESMValTool is built and maintained by an active community of scientists and
+software engineers. It is an open source project to which anyone can
+contribute. Many of the interactions take place on GitHub. Here, we briefly
+introduce you to some of the most important pages.
+
+.. admonition:: Meet the ESMValGroup
+   :class: admonition-todo
+
+   Go to https://github.com/ESMValGroup. This is 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 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?
+
+.. admonition:: Issues and pull requests
+   :class: admonition-todo
+
+   Go back to the repository pages of `ESMValTool <https://github.com/
+   ESMValGroup/ESMValTool>`_ or `ESMValCore <https://github.com/ESMValGroup/
+   ESMValCore>`_. There are tabs for ‘issues’ and ‘pull requests’. You can use
+   the labels to navigate them a bit more. How many open issues are about
+   enhancements of ESMValTool? And how many bugs have been fixed in
+   ESMValCore? There is also an ‘insights’ tab, where you can see a summary
+   of recent activity. How many issues have been opened and closed in the
+   past month?
+
+Conclusion
+----------
+
+This concludes the introduction of the tutorial. You now have a basic
+knowledge of ESMValTool and its community. The following episodes will walk
+you through the installation, configuration and running your first recipes.
+
+.. admonition:: Key points
+   :class: important
+
+   * ESMValTool provides a reliable interface to analyse and evaluate climate
+     data
+   * A large collection of recipes and diagnostic scripts is already available
+   * ESMValTool is built and maintained by an active community of scientists
+     and developers
+
+.. _`PyData Theme documentation: Admonitions`: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/admonitions.html
+.. _`Font Awesome`: https://fontawesome.com/search?ic=free-collection

doc/sphinx/source/tutorials/episode_2_quickstart.rst

@@ -0,0 +1,154 @@
+.. _episode_2_quickstart:
+
+Quickstart guide
+================
+
+.. admonition:: Overview
+   :class: note
+
+   .. grid:: 2
+      :gutter: 1
+      :margin: 3 3 0 5
+
+      .. grid-item-card:: Timings
+         :columns: 12
+
+         * Teaching: 2 min
+         * Exercises: 8 min
+
+      .. grid-item-card:: Questions
+
+         * What is the purpose of the quickstart guide?
+         * How do I load and check the ESMValTool environment?
+         * How do I configure ESMValTool?
+         * How do I run a recipe?
+
+      .. grid-item-card:: Learning outcomes
+
+         * Understand the purpose of the quickstart guide
+         * Load and check the ESMValTool environment
+         * Configure ESMValTool
+         * Run a recipe
+
+      .. grid-item-card:: Compatibility
+         :columns: 12
+
+         ESMValTool v2.15.0
+
+
+What is the purpose of the quickstart guide?
+--------------------------------------------
+
+The purpose of the quickstart guide is to enable a user of ESMValTool to run
+ESMValTool as quickly as possible by making the minimum number of changes.
+
+.. admonition:: Purpose of the quickstart guide
+   :class: discussion
+
+   The purpose of this quickstart guide is to get you running with ESMValTool
+   as quickly as possible without requiring a full tutorial walkthrough.
+
+
+How do I load and check the ESMValTool environment?
+---------------------------------------------------
+
+For this quickstart guide, it is assumed that ESMValTool has already been
+installed at the site where it will be run. If this is not the case, see the
+:doc:`Installation <episode_3_installation>` episode in this tutorial.
+
+Load the ESMValTool environment by following the instructions in the
+:ref:`ESMValTool installation and environment activation guide <install_on_hpc>`.
+This will typically involving loading a module like so:
+
+.. code-block:: bash
+
+   module load esmvaltool
+
+Check the ESMValTool environment by accessing the help for ESMValTool:
+
+.. code-block:: bash
+
+   esmvaltool --help
+
+.. admonition:: Check the ESMValTool environment
+   :class: admonition-todo
+
+   Run the command above to confirm that your ESMValTool environment is loaded
+   correctly and that the command-line interface is available.
+
+
+How do I configure ESMValTool?
+------------------------------
+
+Create the ESMValTool user configuration file. By default, this file is written
+to ``~/.config/esmvaltool/config-user.yml``:
+
+.. code-block:: bash
+
+   esmvaltool config copy defaults/config-user.yml
+
+Edit the ESMValTool user configuration file using your favourite text editor to
+uncomment the lines relating to the site where ESMValTool will be run.
+
+For more details about the ESMValTool user configuration file, see the
+:doc:`Configuration <episode_4_configuration>` episode in this tutorial.
+
+.. admonition:: Configure the tool
+   :class: admonition-todo
+
+   Create the user configuration file and adjust the settings for the machine on
+   which you are running ESMValTool.
+
+
+How do I run a recipe?
+----------------------
+
+Run the example Python recipe:
+
+.. code-block:: bash
+
+   esmvaltool run examples/recipe_python.yml
+
+Wait for the recipe to complete. If the recipe completes successfully, the last
+line printed to the screen at the end of the log will look something like:
+
+.. code-block:: bash
+
+   YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Run was successful
+
+View the output of the recipe by opening the HTML file produced by ESMValTool.
+The location of this file is printed to the screen near the end of the log:
+
+.. code-block:: bash
+
+   YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Wrote recipe output to:
+   file:///$HOME/esmvaltool_output/recipe_python_``<date>_<time>``/index.html
+
+For more details about running recipes, see the
+:doc:`episode_5_recipe` episode in this tutorial.
+
+.. admonition:: Run an example recipe
+   :class: admonition-todo
+
+   Try running the example recipe above and confirm that the run completes
+   successfully before moving on to other recipes.
+
+
+Conclusion
+----------
+
+This quickstart guide introduces the minimum steps needed to get ESMValTool
+running on your system. Once the environment is loaded, configured, and a recipe
+has been run successfully, you are ready to explore the wider tutorial and more
+advanced workflows.
+
+.. admonition:: Key points
+   :class: important
+
+   * The purpose of the quickstart guide is to enable a user to run ESMValTool
+     as quickly as possible without having to go through the whole tutorial.
+   * Use ``module load`` to load the ESMValTool environment.
+   * Use ``esmvaltool --help`` to check that the environment is working.
+   * Use ``esmvaltool config copy defaults/config-user.yml`` to create the user
+     configuration file.
+   * Use ``esmvaltool run ``<recipe>``.yml`` to run a recipe.

doc/sphinx/source/tutorials/episode_3_installation.rst

@@ -0,0 +1,4 @@
+.. _episode_3_installation:
+
+Installation
+============

doc/sphinx/source/tutorials/episode_4_configuration.rst

@@ -0,0 +1,4 @@
+.. _episode_4_configuration:
+
+Configuration
+=============

doc/sphinx/source/tutorials/episode_5_recipe.rst

@@ -0,0 +1,4 @@
+.. _episode_5_recipe:
+
+Running your first recipe
+=========================

doc/sphinx/source/tutorials/index.rst

@@ -3,7 +3,7 @@
 Tutorials
 =========
 
-A tutorial is available on https://tutorial.esmvaltool.org.
+A tutorial is available on :doc:`ESMValTool Tutorial </tutorials/tutorial_overview>`.
 
 Learning resources
 ------------------
@@ -22,8 +22,14 @@ While these are tailored for ACCESS users, they are still very informative.
 .. (test by replacing '<add filename here>' with 'template').
 
 .. toctree::
-   :maxdepth: 1
-   :caption: <add topic heading here>
-
-   template
-.. <add filename here>
+   :hidden:
+   :maxdepth: 2
+   :caption: ESMValTool Tutorial
+
+   Overview <tutorial_overview>
+   Setup <tutorial_setup>
+   Introduction <episode_1_introduction>
+   Quickstart guide <episode_2_quickstart>
+   Installation <episode_3_installation>
+   Configuration <episode_4_configuration>
+   Running your first recipe <episode_5_recipe>

doc/sphinx/source/tutorials/template.rst

@@ -1,4 +1,4 @@
-.. :orphan:  # uncomment before merging!
+:orphan:
 
 .. How to use this template
 ..