diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index f562bf7ecf..492910f848 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/tutorials/files/esmvaltool_output_header.txt b/doc/sphinx/source/tutorials/files/esmvaltool_output_header.txt new file mode 100644 index 0000000000..f77f9be9c9 --- /dev/null +++ b/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! diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 244fbbc453..4cfefa9d3b 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/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 + +.. 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 +.. diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst new file mode 100644 index 0000000000..f9147deedd --- /dev/null +++ b/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. 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]