From f26bea84ef90b20306ef61a398f6e43e183f3ea5 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Wed, 13 May 2026 17:11:19 +0100 Subject: [PATCH 1/6] #4452: Add tutorial template file and a new dependency (sphinx_design) --- doc/sphinx/source/conf.py | 1 + doc/sphinx/source/index.rst | 1 + .../tutorials/esmvaltool_output_header.txt | 31 ++++ doc/sphinx/source/tutorials/index.rst | 17 +++ doc/sphinx/source/tutorials/template.rst | 138 ++++++++++++++++++ pyproject.toml | 1 + 6 files changed, 189 insertions(+) create mode 100644 doc/sphinx/source/tutorials/esmvaltool_output_header.txt create mode 100644 doc/sphinx/source/tutorials/index.rst create mode 100644 doc/sphinx/source/tutorials/template.rst diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index bb13194283..deb6c3ab76 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/sphinx/source/conf.py @@ -53,6 +53,7 @@ "sphinx.ext.viewcode", "sphinx.ext.napoleon", "autodocsumm", + "sphinx_design", ] autodoc_default_options = { diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index e2d29dc839..931010e181 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -65,6 +65,7 @@ Contact information is available :ref:`here `. :caption: ESMValTool Introduction + Tutorials ESMValTool Functionalities Gallery Getting started diff --git a/doc/sphinx/source/tutorials/esmvaltool_output_header.txt b/doc/sphinx/source/tutorials/esmvaltool_output_header.txt new file mode 100644 index 0000000000..f77f9be9c9 --- /dev/null +++ b/doc/sphinx/source/tutorials/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! diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst new file mode 100644 index 0000000000..45dfd3d5a7 --- /dev/null +++ b/doc/sphinx/source/tutorials/index.rst @@ -0,0 +1,17 @@ +.. _tutorials: + +Tutorials +========= + +.. The template 'Table of Contents' below +.. will not render in the HTML documentation +.. until the '' line below is uncommented +.. and a filename is added +.. (test by replacing '' with 'template'). + +.. toctree:: + :maxdepth: 1 + :caption: + +.. + template # remove before merging! diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst new file mode 100644 index 0000000000..ce7fd938bb --- /dev/null +++ b/doc/sphinx/source/tutorials/template.rst @@ -0,0 +1,138 @@ +.. :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. +.. 5. Remove ':orphan:', these comments, +.. and 'The language of tutorials' section (below). +.. +.. https://diataxis.fr/tutorials provides more information. + +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. + +High level step 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`_. +* Include other files from within the documentation: + + .. include:: esmvaltool_output_header.txt + :code: + +High level step 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. 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 diff --git a/pyproject.toml b/pyproject.toml index c0d9f0cf01..9d381f3617 100644 --- a/pyproject.toml +++ b/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] From e6b0ded8f9b0052a12bcbdd9e6a93ac635172df7 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Wed, 13 May 2026 17:15:07 +0100 Subject: [PATCH 2/6] #4452: Ensure template is rendered --- doc/sphinx/source/tutorials/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 45dfd3d5a7..6b1356c600 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -13,5 +13,5 @@ Tutorials :maxdepth: 1 :caption: + template .. - template # remove before merging! From 1ae7d4355f3c2ff76c0696030133c78410fe2c96 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Wed, 13 May 2026 17:40:08 +0100 Subject: [PATCH 3/6] #4452: Resolve conflicts (I did it via the browser but it didn't take) :( --- doc/sphinx/source/index.rst | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 725fd7ad88..a0adab260f 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -39,21 +39,6 @@ notebooks. :maxdepth: 2 :caption: ESMValTool -<<<<<<< 4452_add_tutorial_template_file - Introduction - Tutorials - ESMValTool Functionalities - Gallery - Getting started - Recipes - Diagnostics API Reference - Obtaining input data - Making a recipe or diagnostic - Contributing to the community - Utilities - Frequently Asked Questions - Changelog -======= Introduction Tutorials ESMValTool Functionalities @@ -68,7 +53,6 @@ notebooks. Frequently Asked Questions Changelog Support ->>>>>>> main Indices and tables ------------------ From fea048b63c944318e6344cc3b5e42a4076c57536 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Thu, 14 May 2026 06:28:31 +0100 Subject: [PATCH 4/6] #4452: Move file to a 'files' directory to mirror Software Carpentry tutorial structure --- .../source/tutorials/{ => files}/esmvaltool_output_header.txt | 0 doc/sphinx/source/tutorials/template.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename doc/sphinx/source/tutorials/{ => files}/esmvaltool_output_header.txt (100%) diff --git a/doc/sphinx/source/tutorials/esmvaltool_output_header.txt b/doc/sphinx/source/tutorials/files/esmvaltool_output_header.txt similarity index 100% rename from doc/sphinx/source/tutorials/esmvaltool_output_header.txt rename to doc/sphinx/source/tutorials/files/esmvaltool_output_header.txt diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst index ce7fd938bb..af40661eac 100644 --- a/doc/sphinx/source/tutorials/template.rst +++ b/doc/sphinx/source/tutorials/template.rst @@ -64,7 +64,7 @@ Add content here. * Use admonitions from `PyData Theme documentation: Admonitions`_. * Include other files from within the documentation: - .. include:: esmvaltool_output_header.txt + .. include:: files/esmvaltool_output_header.txt :code: High level step 2 From ef431ca5d7ea82cfaa8333ca94e1094699c13ee2 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Thu, 14 May 2026 06:29:50 +0100 Subject: [PATCH 5/6] #4452: Update headings to better align with terms used in the overview --- doc/sphinx/source/tutorials/template.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst index af40661eac..e89bf23420 100644 --- a/doc/sphinx/source/tutorials/template.rst +++ b/doc/sphinx/source/tutorials/template.rst @@ -54,8 +54,8 @@ Title of the tutorial * Assumption 1. * Assumption 2. -High level step 1 ------------------ +Question 1 +---------- Add content here. @@ -67,8 +67,8 @@ Add content here. .. include:: files/esmvaltool_output_header.txt :code: -High level step 2 ------------------ +Question 2 +---------- Add content here. From 0ed220f4ba0415f6ec25e00be6a2d1f9d7e9ac24 Mon Sep 17 00:00:00 2001 From: Emma Hogan Date: Thu, 14 May 2026 06:40:19 +0100 Subject: [PATCH 6/6] #4452: Add examples links to pages and sections within the documentation --- doc/sphinx/source/tutorials/template.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst index e89bf23420..f9147deedd 100644 --- a/doc/sphinx/source/tutorials/template.rst +++ b/doc/sphinx/source/tutorials/template.rst @@ -7,12 +7,15 @@ .. 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. +.. 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 ===================== @@ -62,7 +65,14 @@ 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`_. -* Include other files from within the documentation: +* 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: