ESMValGroup · LisaBock · Aug 12, 2026 · Aug 12, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/doc/sphinx/source/tutorials/episode_1.rst b/doc/sphinx/source/tutorials/episode_1.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
diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst
@@ -5,6 +5,8 @@ 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 +24,10 @@ 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>
+   :hidden:
+   :maxdepth: 2
+   :caption: ESMValTool Tutorial
 
-   template
-.. <add filename here>
+   Overview <tutorial_overview>
+   Setup <tutorial_setup>
+   Introduction <episode_1>
diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst
@@ -1,4 +1,4 @@
-.. :orphan:  # uncomment before merging!
+:orphan:
 
 .. How to use this template
 ..

diff --git a/doc/sphinx/source/tutorials/tutorial_overview.rst b/doc/sphinx/source/tutorials/tutorial_overview.rst
@@ -0,0 +1,103 @@
+.. _tutorial_overview:
+
+ESMValTool Tutorial
+===================
+
+This tutorial helps you to use ESMValTool.
+
+The Earth System Model Evaluation Tool (ESMValTool) is a community developed
+software toolkit that aims to facilitate the diagnosis and evaluation of the
+causes and effects of model biases and inter-model spread within the CMIP model
+ensemble.
+
+This tutorial is structured into ``basic`` and ``advanced`` topics such that
+episodes starting from the **Introduction** up to the episode on **Conclusion
+of the basic tutorial** all cover basic topics and can be done in one sitting.
+
+The remaining episodes cover the ``advanced`` topics and each episode is a
+mini-tutorial covering an advanced aspect of working with ESMValTool. These
+mini-tutorials can be appended to the main tutorial or worked through
+independently.
+
+.. admonition:: What will you learn in this course
+    :class: note
+
+    * What is ESMValTool
+    * How to install ESMValTool
+    * How to configure ESMValTool for your local system
+    * How to run ESMValTool
+    * How to work with ESMValTool's suite of preprocessors
+    * How to debug your recipes
+    * How to access and deploy recipes from the ESMValTools gallery (Advanced)
+    * How to develop your own diagnostics and recipes (Advanced)
+    * How to contribute your recipes and diagnostics back into ESMValTool
+      (Advanced)
+    * How to include new observational datasets (Advanced)
+    * How to handle errors and warnings (Advanced)
+    * How to use ESMValCore API with Jupyter notebooks (Advanced)
+
+.. admonition:: Prerequisites
+    :class: important
+
+    The prerequisites for the tutorial are listed on the :doc:`tutorial setup
+    page </tutorials/tutorial_setup>`.
+
+Main things you need to know before starting this course
+--------------------------------------------------------
+
+1. This tutorial can be taken online independently or taught by one of our
+   instructors.
+2. Don't be alarmed if you can't work through the entire tutorial in one
+   sitting. It may take some time to get used to working with ESMValTool.
+3. If you get stuck, help is always available from the tutors, from ESMValTool
+   developers via the `github issues page
+   <https://github.com/ESMValGroup/ESMValTool/issues>`_
+   or via the `ESMValTool discussion page
+   <https://github.com/ESMValGroup/ESMValTool/discussions>`_.
+4. This tutorial includes several advanced lessons after the conclusion. These
+   advanced lessons should be treated like “mini-tutorials”, and include aspects
+   like **Developing your own diagnostic** or **How to include observations**.
+
+.. admonition:: Additional resources
+    :class: note
+
+    * :doc:`Documentation <\index>`
+    * `ESMValTool home page <https://www.esmvaltool.org/>`_
+    * `ESMValTool discussion page
+      <https://github.com/ESMValGroup/ESMValTool/discussions>`_
+    * `Publications <https://esmvaltool.org/references/>`_
+    * `ESMValTool Source code <https://github.com/ESMValGroup/ESMValTool>`_
+    * `ESMValCore Source code <https://github.com/ESMValGroup/ESMValCore>`_
+    * `ESMValTool Citation info <https://esmvaltool.org/references/>`_
+
+How to site the tutorial
+------------------------
+
+Please use citation information available at
+https://doi.org/10.5281/zenodo.3974591.
+
+Schedule
+--------
+
+.. tabularcolumns:: |p{3cm}|p{5cm}|p{3cm}|
+
++--------+----------------------------------+----------------------------------------+
+|        | :doc:`Setup <tutorial_setup>`    | Download files required for the lesson |
++--------+----------------------------------+----------------------------------------+
+|| 00:00 || :doc:`episode_1`                || What is ESMValTool?                   |
+||       ||                                 || Who are the people behind ESMValTool? |
++--------+----------------------------------+----------------------------------------+
+|        | Quickstart guide                 |                                        |
++--------+----------------------------------+----------------------------------------+
+|        | Installation                     |                                        |
++--------+----------------------------------+----------------------------------------+
+|        | Configuration                    |                                        |
++--------+----------------------------------+----------------------------------------+
+|        | Running your first recipe        |                                        |
++--------+----------------------------------+----------------------------------------+
+|        | Conclusion of the basic tutorial |                                        |
++--------+----------------------------------+----------------------------------------+
+
+
+The actual schedule may vary slightly depending on the topics and exercises
+chosen by the instructor.