Add template file for tutorial pages

doc/sphinx/source/conf.py

@@ -53,6 +53,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "autodocsumm",
+    "sphinx_design",
 ]
 
 autodoc_default_options = {

doc/sphinx/source/tutorials/files/esmvaltool_output_header.txt

@@ -0,0 +1,31 @@
+2026-05-11 15:22:20,686 UTC [280110] INFO
+______________________________________________________________________
+          _____ ____  __  ____     __    _ _____           _
+         | ____/ ___||  \/  \ \   / /_ _| |_   _|__   ___ | |
+         |  _| \___ \| |\/| |\ \ / / _` | | | |/ _ \ / _ \| |
+         | |___ ___) | |  | | \ V / (_| | | | | (_) | (_) | |
+         |_____|____/|_|  |_|  \_/ \__,_|_| |_|\___/ \___/|_|
+______________________________________________________________________
+
+Earth System Model Evaluation Tool
+
+A community tool for the evaluation of Earth system models.
+
+https://esmvaltool.org
+
+The Earth System Model Evaluation Tool (ESMValTool) is a community
+diagnostics and performance metrics tool for the evaluation of Earth
+System Models (ESMs) that allows for routine comparison of single or
+multiple models, either against predecessor versions or against
+observations.
+
+Tutorial: https://tutorial.esmvaltool.org
+Documentation: https://docs.esmvaltool.org
+Contact: esmvaltool-dev@listserv.dfn.de
+
+If you find this software useful for your research, please cite it using
+https://doi.org/10.5281/zenodo.3387139 for ESMValCore or
+https://doi.org/10.5281/zenodo.3401363 for ESMValTool or
+any of the reference papers listed at https://esmvaltool.org/references/.
+
+Have fun!

doc/sphinx/source/tutorials/index.rst

@@ -1,3 +1,5 @@
+.. _tutorials:
+
 Tutorials
 =========
 
@@ -12,3 +14,16 @@ While these are tailored for ACCESS users, they are still very informative.
 .. raw:: html
 
    <iframe width="560" height="315" src="https://www.youtube.com/embed/videoseries?si=pUXrXB8C8bLRfQHY&amp;list=PLFjfi2xLaFpJp59LvDc1upQsj_xzFlFLc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+.. The template 'Table of Contents' below
+.. will not render in the HTML documentation
+.. until the '<add filename here>' line below is uncommented
+.. and a filename is added
+.. (test by replacing '<add filename here>' with 'template').
+
+.. toctree::
+   :maxdepth: 1
+   :caption: <add topic heading here>
+
+   template
+.. <add filename here>

doc/sphinx/source/tutorials/template.rst

@@ -0,0 +1,148 @@
+.. :orphan:  # uncomment before merging!
+
+.. How to use this template
+..
+.. 1. Make a copy of this file.
+.. 2. Update the filename.
+.. 3. Add the filename (without the '.rst' extension)
+..    to a 'toctree' directive
+..    in the 'tutorials/index.rst' file.
+.. 4. Use the name of the tutorial for the title below
+..    and the reference label.
+.. 5. Remove ':orphan:', these comments,
+..    and 'The language of tutorials' section (below).
+..
+.. https://diataxis.fr/tutorials provides more information.
+
+.. _title_of_the_tutorial:
+
+Title of the tutorial
+=====================
+
+.. admonition:: Overview
+   :class: note
+
+   .. grid:: 2
+      :gutter: 1
+      :margin: 3 3 0 5
+
+      .. grid-item-card:: Timings
+         :columns: 12
+
+         * Teaching: X min
+         * Exercises: Y min
+
+      .. grid-item-card:: Questions
+
+         * Describe what the learner will accomplish.
+         * Question 1?
+         * Question 2?
+
+      .. grid-item-card:: Learning outcomes
+
+         * Describe the learning outcomes, i.e.
+           the knowledge, skills, or expertise the learner will gain.
+         * Objective 1.
+         * Objective 2.
+
+      .. grid-item-card:: Prerequisites
+
+         * Provide any prerequisites.
+         * Prerequisites 1.
+         * Prerequisites 2.
+
+      .. grid-item-card:: Assumptions
+
+         * Provide any assumptions.
+         * Assumption 1.
+         * Assumption 2.
+
+Question 1
+----------
+
+Add content here.
+
+* Consider including diagrams to support the text.
+* Use any free icons from `Font Awesome`_ via an ``:fa:`` directive.
+* Use admonitions from `PyData Theme documentation: Admonitions`_.
+* Link to other files within the documentation:
+
+  * Link to pages via ``:doc:`/develop/recipe```
+    (renders as :doc:`/develop/recipe`).
+  * Link to sections via ``:ref:`diagnostic_from_example```
+    (renders as :ref:`diagnostic_from_example`).
+
+* Include other files within the documentation:
+
+  .. include:: files/esmvaltool_output_header.txt
+     :code:
+
+Question 2
+----------
+
+Add content here.
+
+* Use code snippets:
+
+  .. code-block:: bash
+     :caption: Bash
+
+     my command
+
+  .. code-block:: python
+     :caption: Python
+     :linenos:
+     :emphasize-lines: 2
+
+     with line numbers
+     and code highlighting
+
+* Create expandable sections containing the
+  output / answer / solution from a command:
+
+  .. dropdown:: Output
+     :color: secondary
+     :icon: eye
+
+     .. code-block:: bash
+        :caption: Bash
+
+        my output
+
+The language of tutorials
+-------------------------
+
+We ...
+    The first-person plural
+    affirms the relationship between tutor and learner:
+    you are not alone; we are in this together.
+
+First, do x. Now, do y. Now that you have done y, do z.
+    No room for ambiguity or doubt.
+
+We must always do x before we do y. <explanation> provides more details.
+    Provide minimal explanation of actions
+    in the most basic language possible.
+    Link to more detailed explanation.
+
+The output should be something like ...
+    Give your learner clear expectations.
+
+Notice that ... Remember that ... Let's check ...
+    Give your learner plenty of clues
+    to help confirm they are on the right track and orient themselves.
+
+Congratulations!
+----------------
+
+You have built a secure, three-layer hylomorphic stasis engine ...
+    Describe (and admire, in a mild way) what your learner has accomplished.
+
+.. admonition:: Key points
+   :class: important
+
+   * Key point 1
+   * Key point 2
+
+.. _`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

pyproject.toml

@@ -324,6 +324,7 @@ test-py313 = { features = ["py313", "esmvalcore", "test"], solve-group = "defaul
 "myst-nb" = "*"
 "pydata-sphinx-theme" = "*"
 "sphinx" = ">=6.1.3,<9"     # <9 due to ESMValTool/issues/4316
+"sphinx-design" = "*"
 
 # Other development tools.
 [tool.pixi.feature.dev.dependencies]