#3724: Add custom jinja2 test. Rename site recipes file. Revise docs

esmvaltool/utils/recipe_test_workflow/Jinja2Tests/file_exists.py

@@ -1,7 +1,37 @@
+"""
+Module for custom Jinja2 Tests.
+
+In Jinja2 "tests" are used to test a variable against an expression.
+Refer to Jinja2 tests:
+https://jinja.palletsprojects.com/en/stable/templates/#tests
+
+Jinja2 has a number of Builtin tests:
+https://jinja.palletsprojects.com/en/stable/templates/#list-of-builtin-tests
+
+Jinja2 also allows for writing custom tests in Python:
+https://jinja.palletsprojects.com/en/stable/api/#custom-tests
+
+Cylc supports custom filters, tests and globals as described here:
+https://cylc.github.io/cylc-doc/stable/html/user-guide/writing-workflows/jinja2.html#custom-jinja2-filters-tests-and-globals
+
+"""
 from pathlib import Path
 
 
 def file_exists(file_path):
+    """
+    Test if a file exists.
+
+    Parameters
+    ----------
+    file_path : str
+        A file path.
+
+    Returns
+    -------
+    bool
+        Returns True if the file exists.
+    """
     run_directory = Path.cwd()
     site_recipes_file_path = run_directory / file_path
     return site_recipes_file_path.is_file()

esmvaltool/utils/recipe_test_workflow/flow.cylc

@@ -1,26 +1,17 @@
 #!jinja2
 {{ assert(SITE != "", "SITE must be set to something other than an empty string") }}
 
-{% set SITE_RECIPES_FILE = "site/" ~ SITE ~ "-recipes.cylc" %}
+{% set SITE_RECIPES_FILE = "site/" ~ SITE ~ "-recipes.jinja" %}
 {% set MISSING_FILE_MSG =
     "'" ~ SITE_RECIPES_FILE ~ "' is required for the Recipe Test Workflow and was not "
     "found - the 'How to add a recipe to the RTW' documentation provides more "
     "information"%}
 {% set UNDEFINED_VARIABLE_MSG =
-    "variable must be set in your '" ~ SITE_RECIPES_FILE ~ "'- the 'How to add a recipe "
-    "to the RTW' documentation provides more information."%}
-
-# Assert 'site/<site>-recipes.cylc' exists and assert FAST_RECIPES and MEDIUM_RECIPES
-# are imported from it. Produce readable errors if not.
-# --- Text in the three lines above an assert appears in the Jinja2 error ---
-
-
+    "variable must be set in your '" ~ SITE_RECIPES_FILE ~ "' file - the 'How "
+    "to add a recipe to the RTW' documentation provides more information."%}
 
 {{ assert(SITE_RECIPES_FILE is file_exists, MISSING_FILE_MSG) }}
 {% from SITE_RECIPES_FILE import FAST_RECIPES, MEDIUM_RECIPES %}
-# --- Text in the three lines above an assert appears in the Jinja2 error ---
-
-
 
 {{ assert(FAST_RECIPES is defined, "The FAST_RECIPES " ~ UNDEFINED_VARIABLE_MSG) }}
 {{ assert(MEDIUM_RECIPES is defined, "The MEDIUM_RECIPES " ~ UNDEFINED_VARIABLE_MSG) }}

esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.cylc → esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.jinja

@@ -1,14 +1,19 @@
-#   This file contains the recipes that are run by the RTW at the Met Office.
-#   The "How to add a recipe to the RTW" documentation provides more information.
+# This file contains the recipes that are run by the RTW at the Met Office.
+# The "How to add a recipe to the RTW" documentation provides more information.
 #
-#   KEYS                VALUES
-#   ----                ------
-#   recipe_path         Recipe paths are specified relative to esmvaltool/recipes. For
-#                       recipes in subdirectories, `--` stands for `/` since the latter
-#                       is an illegal char.
-#   actual              Example recorded usage at Met Office.
-#   max_time            The maximum amount of time the recipe has to complete.
-#   max_memory          The memory to allocate to running the recipe.
+# KEYS         VALUES
+# ----         ------
+# recipe_path  The path to the recipe. Recipe paths are specified relative to
+#              esmvaltool/recipes. For recipes in subdirectories, `--` stands
+#              for `/` since the latter is an illegal char.
+# actual       A note of  the recipe's actual resource usage. From the
+#              successful run of the recipe on the compute server at your site.
+# max_time     The maximum amount of time the recipe has to complete. Use the
+#              ISO8601 duration format (see
+#              `Cylc ISO8601 Durations`_ for more).
+# max_memory   The memory allocated to running the recipe. Default units are
+#              megabytes. Different units can be specified using the suffix
+#              [K|M|G|T] (see `Slurm sbatch --mem`_ for more).
 
 {% set FAST_RECIPES =
     [