Add how to add a recipe documentation

.github/workflows/rtw-env/rtw-env.lock

@@ -8,7 +8,7 @@ https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-inconsolata-3.000-h77eed37_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-source-code-pro-2.038-h77eed37_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-ubuntu-0.83-h77eed37_2.conda
-https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.40-h55db66e_0.conda
+https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.40-hf3520f5_1.conda
 https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-ng-13.2.0-hc0a3c3a_7.conda
 https://conda.anaconda.org/conda-forge/linux-64/python_abi-3.11-4_cp311.conda
 https://conda.anaconda.org/conda-forge/noarch/tzdata-2024a-h0c530f3_0.conda
@@ -38,7 +38,7 @@ https://conda.anaconda.org/conda-forge/linux-64/libwebp-base-1.4.0-hd590300_0.co
 https://conda.anaconda.org/conda-forge/linux-64/libxcrypt-4.4.36-hd590300_1.conda
 https://conda.anaconda.org/conda-forge/linux-64/libzlib-1.2.13-hd590300_5.conda
 https://conda.anaconda.org/conda-forge/linux-64/ncurses-6.5-h59595ed_0.conda
-https://conda.anaconda.org/conda-forge/linux-64/openssl-3.3.0-hd590300_0.conda
+https://conda.anaconda.org/conda-forge/linux-64/openssl-3.3.0-h4ab18f5_3.conda
 https://conda.anaconda.org/conda-forge/linux-64/pixman-0.43.2-h59595ed_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/pthread-stubs-0.4-h36c2ea0_1001.tar.bz2
 https://conda.anaconda.org/conda-forge/linux-64/xorg-kbproto-1.0.7-h7f98852_1002.tar.bz2
@@ -83,7 +83,7 @@ https://conda.anaconda.org/conda-forge/noarch/charset-normalizer-3.3.2-pyhd8ed1a
 https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/cycler-0.12.1-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/dbus-1.13.6-h5008d03_3.tar.bz2
-https://conda.anaconda.org/conda-forge/linux-64/docutils-0.20.1-py311h38be061_3.conda
+https://conda.anaconda.org/conda-forge/noarch/docutils-0.21.2-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/empy-3.3.4-pyh9f0ad1d_1.tar.bz2
 https://conda.anaconda.org/conda-forge/linux-64/fontconfig-2.14.2-h14ed4e7_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/gdk-pixbuf-2.42.12-hb9ae30d_0.conda
@@ -110,9 +110,10 @@ https://conda.anaconda.org/conda-forge/noarch/pyparsing-3.1.2-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/pysocks-1.7.1-pyha2e5f31_6.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/pytz-2024.1-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/rx-3.2.0-pyhd8ed1ab_0.tar.bz2
-https://conda.anaconda.org/conda-forge/noarch/setuptools-69.5.1-pyhd8ed1ab_0.conda
+https://conda.anaconda.org/conda-forge/noarch/setuptools-70.0.0-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/six-1.16.0-pyh6c4a22f_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-2.2.0-pyhd8ed1ab_0.tar.bz2
+https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-1.0.1-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/tomli-2.0.1-pyhd8ed1ab_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/typing_extensions-4.11.0-pyha770c72_0.conda
@@ -122,11 +123,13 @@ https://conda.anaconda.org/conda-forge/linux-64/xorg-libxext-1.3.4-h0b41bf4_2.co
 https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrender-0.9.11-hd590300_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/zeromq-4.3.5-h75354e8_4.conda
 https://conda.anaconda.org/conda-forge/noarch/zipp-3.17.0-pyhd8ed1ab_0.conda
+https://conda.anaconda.org/conda-forge/noarch/accessible-pygments-0.0.4-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/ansimarkup-1.5.0-pyh44b312d_0.tar.bz2
 https://conda.anaconda.org/conda-forge/noarch/babel-2.14.0-pyhd8ed1ab_0.conda
+https://conda.anaconda.org/conda-forge/noarch/beautifulsoup4-4.12.3-pyha770c72_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/cairo-1.18.0-h3faef2a_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/cffi-1.16.0-py311hb3a22ac_0.conda
-https://conda.anaconda.org/conda-forge/linux-64/fonttools-4.51.0-py311h459d7ec_0.conda
+https://conda.anaconda.org/conda-forge/linux-64/fonttools-4.52.1-py311h331c9d8_0.conda
 https://conda.anaconda.org/conda-forge/noarch/importlib-metadata-7.1.0-pyha770c72_0.conda
 https://conda.anaconda.org/conda-forge/noarch/jaraco.classes-3.4.0-pyhd8ed1ab_1.conda
 https://conda.anaconda.org/conda-forge/noarch/jinja2-3.0.3-pyhd8ed1ab_0.tar.bz2
@@ -150,7 +153,7 @@ https://conda.anaconda.org/conda-forge/noarch/graphql-core-2.2-py_0.tar.bz2
 https://conda.anaconda.org/conda-forge/linux-64/harfbuzz-8.5.0-hfac3d4d_0.conda
 https://conda.anaconda.org/conda-forge/noarch/importlib_metadata-7.1.0-hd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/numpy-1.26.4-py311h64a7726_0.conda
-https://conda.anaconda.org/conda-forge/noarch/requests-2.31.0-pyhd8ed1ab_0.conda
+https://conda.anaconda.org/conda-forge/noarch/requests-2.32.2-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/urwid-2.6.12-py311h331c9d8_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/contourpy-1.2.1-py311h9547e67_0.conda
 https://conda.anaconda.org/conda-forge/noarch/graphql-relay-2.0.1-py_0.tar.bz2
@@ -161,19 +164,18 @@ https://conda.anaconda.org/conda-forge/noarch/graphene-2.1.9-pyhd8ed1ab_0.tar.bz
 https://conda.anaconda.org/conda-forge/linux-64/gtk2-2.24.33-h280cfa0_4.conda
 https://conda.anaconda.org/conda-forge/linux-64/keyring-23.13.1-py311h38be061_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/librsvg-2.58.0-hadf69e7_1.conda
-https://conda.anaconda.org/conda-forge/linux-64/matplotlib-base-3.8.4-py311h54ef318_0.conda
+https://conda.anaconda.org/conda-forge/linux-64/matplotlib-base-3.8.4-py311ha4ca890_2.conda
 https://conda.anaconda.org/conda-forge/noarch/cylc-flow-base-8.2.7-pyh707e725_0.conda
 https://conda.anaconda.org/conda-forge/linux-64/graphviz-9.0.0-h78e8752_1.conda
 https://conda.anaconda.org/conda-forge/noarch/metomi-rose-base-2.2.0-pyh707e725_0.conda
 https://conda.anaconda.org/conda-forge/noarch/cylc-flow-8.2.7-pyh48b6436_0.conda
 https://conda.anaconda.org/conda-forge/noarch/cylc-rose-1.3.4-pyh707e725_0.conda
-https://conda.anaconda.org/conda-forge/linux-64/pygraphviz-1.12-py311hbf5cbc9_0.conda
+https://conda.anaconda.org/conda-forge/linux-64/pygraphviz-1.13-py311hf355b97_0.conda
 https://conda.anaconda.org/conda-forge/noarch/metomi-rose-2.2.0-pyh707e725_0.conda
+https://conda.anaconda.org/conda-forge/noarch/pydata-sphinx-theme-0.15.2-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda
-https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jquery-4.1-pyhd8ed1ab_0.conda
-https://conda.anaconda.org/conda-forge/noarch/sphinx_rtd_theme-2.0.0-pyha770c72_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-1.0.7-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinx-7.3.7-pyhd8ed1ab_0.conda
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-1.1.10-pyhd8ed1ab_0.conda

.github/workflows/rtw-env/rtw-env.yml

@@ -9,4 +9,4 @@ dependencies:
   - cylc-rose
   - metomi-rose
   - sphinx
-  - sphinx_rtd_theme
+  - pydata-sphinx-theme

esmvaltool/utils/recipe_test_workflow/doc/source/conf.py

@@ -16,7 +16,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Recipe Test Workflow (RTW)'
+project = 'RTW'
 version = "0.1.0"
 
 # -- General configuration ---------------------------------------------------
@@ -39,7 +39,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/adding_a_recipe.rst

@@ -0,0 +1,100 @@
+Adding a recipe to the Recipe Test Workflow (|RTW|)
+===================================================
+
+.. include:: ../common.txt
+
+**Please note:** Before you follow these steps to add your recipe, you must be
+able to successfully run it with ESMValtool without error.
+
+* Run ESMValTool locally with your recipe, make sure to take note of the memory
+  and time expenditure provided by the terminal output::
+
+    esmvaltool run <your_recipe_name.yml>
+
+* Run the same recipe on JASMIN, again taking note of the memory and time
+  expenditure printed to the terminal.
+
+* Stop any running recipe_test_workflow workflows::
+
+    cylc stop "a_running_recipe_test_workflow"
+
+* Add the recipe to the ``[task parameters]`` section of the |RTW| ``flow.cylc``
+  workflow file, make sure your recipe name fits the formatting of ``recipe_new_
+  recipe \\``.
+
+* Run the workflow. The process task for the new recipe should succeed, but its
+  compare task should fail with an error that the reference data (KGO) does
+  not exist::
+
+    cylc vip -O <your_site_name>
+
+* Locate the workflow run folder of the workflow you just completed.
+
+* Copy the output files from the "cycle" folder (run/share/bin/cycle) of the
+  workflow you just ran, to your site specific KGO rootpath folder
+  (this folder should be set as the value for the variable "KGO_ROOT_PATH="
+  in your rose-suite<your_site>.conf file)::
+
+    cp -r <directory_of_recipe_output_cycle_folder> <KGO_rootpath_folder>
+
+* Change directory to the rootpath KGO directory::
+
+    cd <KGO_rootpath_directory>
+
+* Allow write permissions for all users on the directory and it's
+  subdirectories of the recipe you've added to the KGO folder::
+
+    chmod a+w <the_directory_of_the_recipe_you_have_copied_into_the_KGO_folder>
+
+* Run the RTW again::
+
+    cylc vip -O <your_site_name>
+
+* The workflow should now succeed.
+
+* Take note of how long the run took  to complete on cylc. This can be found in the `job.time` section of the task listed as `process_<your_recipe>`.
+
+* Locate your local <site>.cylc file, found in (recipe_test_workflow/site).
+
+* Open it in your preferred code editor.
+
+* Locate the `COMPUTE` section, it should look something like this::
+
+    [[COMPUTE]]
+    platform = <your_platform_here>
+    execution time limit = PT2M
+    [[[directives]]]
+    --wckey = RTW
+    --ntasks = {{ MAX_PARALLEL_TASKS }}
+    --mem = 2G
+
+* Compare the `execution time limit` and --mem (memory) units here with the
+  readings you took locally. If your local readings do not exceed these, then
+  you have successfully added the recipe to the workflow, and can now commit
+  and push your changes.
+
+
+* If either of the time/memory readings from your local run are larger than the
+  values specified in the `COMPUTE` section, you need to add your recipe as
+  another `process` similar to::
+
+    [[process<fast=recipe_albedolandcover>]]
+    # Actual: 0m31s, 2.5 GB on 2024-04-08.
+    execution time limit = PT2M
+    [[[directives]]]
+        --mem = 3G
+
+* Variable (fast, medium) must be consistent with flow.cylc.
+
+* The commented "Actual" reading should be the time/memory
+  reading you recorded from cylc review.
+
+* Adjust the values for `execution_time` and `--mem` to be larger than the
+  values you recorded from cylc review.
+
+* Stop any running workflows.
+
+* Run the recipe test workflow again.
+
+* If the workflow succeeds then your recipe has successfully been added to the
+  workflow. You can now commit your changes and push them onto GitHub.

esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/index.rst

@@ -7,3 +7,4 @@ User Guide
 
    quick_start
    workflow
+   adding_a_recipe

esmvaltool/utils/recipe_test_workflow/recipe_test_workflow/flow.cylc

@@ -3,8 +3,6 @@
     UTC mode = True
 
 [task parameters]
-    # `fast` recipes are those taking less than 10 mins.
-    # Other recipes should be included in `medium`.
     # Recipe paths are specified relative to esmvaltool/recipes. For recipes in
     # subdirectories, `--` stands for `/` since the latter is an illegal char.
     fast = recipe_radiation_budget, \