Use site-specific lists of recipes in the RTW #3856
Conversation
chrisbillowsMO
added
the
Recipe Test Workflow (RTW)
There was a problem hiding this comment.
Great work @chrisbillowsMO 🥳
I haven't yet reviewed the documentation, but I have run out of time today, so I'm sharing the review comments I have made so far. It's unlikely I'll have any time tomorrow to complete the review, so I'll do it first thing on Monday 👍
| - The files use the Jinja2 templating language (see this | ||
| :ref:`note <jinja2_templating_language>`, the `Cylc Jinja2`_ documentation | ||
| or the `Jinja2`_ documentation for more information). |
There was a problem hiding this comment.
Adding a link to more infomation (the first link) is great! 🥳 I wonder whether this second link should be included somewhere within the first link (if that's where more information about the files is located)? 🤔
There was a problem hiding this comment.
The second and third links were in the first link AS WELL...! Which is how I prefer it - but I merrily defer to the single source of truth doctrine. Despicable duplicate links removed here: 3445729 😉
There was a problem hiding this comment.
A summary of the discussion Chris and I had just now: we agreed to remove the second point completely from this file, since the Jinja2 information is available in the documentation linked to in the first point. I'll add a separate comment to suggest potentially moving the Jinja2 information to the top of the documentation 😊
| "is undefined and must be set, usually in '" ~ SITE_RECIPES_FILE ~ " - see 'How to " | ||
| "add a recipe to the RTW' documentation for more information." |
There was a problem hiding this comment.
Clarify the request. Also, I found out recently that, when writing documentation: use inclusive language that doesn't always refer to "seeing" an element. Unfortunately this is something I used to do a lot and I keep finding occurrences of it! 😱 I have made a suggestion below, but feel free to adjust 😊
| "is undefined and must be set, usually in '" ~ SITE_RECIPES_FILE ~ " - see 'How to " | |
| "add a recipe to the RTW' documentation for more information." | |
| "is undefined and must be set in '" ~ SITE_RECIPES_FILE ~ ". The 'How to " | |
| "add a recipe to the RTW' documentation provides more information." |
There was a problem hiding this comment.
I commited your suggestion but have reverted the . to a - (keeping your text) here: 2bb79fc
Jinja2 renders . as a line break.
E.g.
Jinja2Error: Jinja2 Assertion Error: FAST_RECIPES is undefined and must be set in 'site/metoffice-recipes.cylc'.
The 'How to add a recipe to the RTW' documentation provides more
information.
I did experiment with getting a . (e.g. using \., {% raw %} from here, using an utf-8 full stop) - but it made me feel like too much of a failure. I could live with the dash...!
(I didn't comment it in the file; it didn't feel a big enough issue. Let me know if we should have a comment)
esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.cylc
Outdated
Show resolved
Hide resolved
esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.cylc
Outdated
Show resolved
Hide resolved
esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.cylc
Outdated
Show resolved
Hide resolved
esmvaltool/utils/recipe_test_workflow/site/metoffice-recipes.cylc
Outdated
Show resolved
Hide resolved
| {% set SITE_RECIPES_FILE = 'site/' ~ SITE ~ '-recipes.cylc' %} | ||
| {% from SITE_RECIPES_FILE import FAST_RECIPES, MEDIUM_RECIPES %} |
There was a problem hiding this comment.
I know you spent a lot of time investigating this, and apologies if you already told me the answer to this question, but if the file is included (e.g. {% include 'site/' ~ SITE ~ '-recipes.cylc' %}) are the FAST_RECIPES and MEDIUM_RECIPES variables not recognised? 🤔
Co-authored-by: Emma Hogan <[email protected]>
Co-authored-by: Emma Hogan <[email protected]>
Co-authored-by: Emma Hogan <[email protected]>
Co-authored-by: Emma Hogan <[email protected]>
There was a problem hiding this comment.
Thanks again @chrisbillowsMO! 🎉 I am pleased with the removal of some of the more complex parts of those instructions! 🥳
| If the recipe takes less than 10 minutes to run then it should be added | ||
| to the ``fast`` option. Recipes that take longer than ten minutes should | ||
| be added to the ``medium`` option. | ||
| Run a Recipe in the |RTW| |
There was a problem hiding this comment.
I feel this heading should be "Add the recipe to the RTW", but that's quite similar to the title of this documentation page! 😱
| #. ``<site>-recipes.cylc`` contains **two lists of dictionaries**. The lists | ||
| are ``FAST_RECIPES`` and ``MEDIUM_RECIPES``. |
There was a problem hiding this comment.
Each point must describe an instruction. This point contains only information, which means it would be better located in an info (or equivalent) box.
| #. The recipe should now be added to your ``<site>-recipes.cylc`` file. (Where | ||
| ``<site>`` is your site). Find this in the | ||
| ``esmvaltool/utils/recipe_test_workflow/site/`` directory. Add the recipe in | ||
| alphabetical order for easy user reference: | ||
| :ref:`Currently tested recipes <currently_tested_recipes>`. |
There was a problem hiding this comment.
Use more commanding language, e.g. "Add the recipe to the <site>-recipes.cylc file in the esmvaltool/utils/recipe_test_workflow/site/ directory. Then maybe add the "in alphabetical order" to a "note" box?
| * - ``actual`` | ||
| - A note of the recipe's actual resource usage. From the successful run | ||
| of the recipe on the compute server at your site. |
There was a problem hiding this comment.
Would it be worth including the text in point 3 above here (i.e. how to get this information from the ESMValTool log)?
| .. _jinja2_templating_language: | ||
|
|
||
| .. note:: | ||
| The ``<site>-recipes.cylc`` file is actually written in the `Jinja2`_ | ||
| templating language. Jinja2 gives |Cylc| many powerful features (visit | ||
| `Cylc Jinja2`_). This is beyond the scope of this guide. Follow the links | ||
| for more information. |
There was a problem hiding this comment.
I feel the opening points of this documentation should be updated to give more information about what will happen when adding a recipe. For example, they will be editing a single file in the RTW, and it's Jinja2, and then include this information.
| #. Once the recipe dictionary is added to either ``FAST_RECIPES`` or | ||
| ``MEDIUM_RECIPES``, the recipe will run as part of the |RTW| at your site. | ||
| Next, the recipe will need |KGOs| to run successfully in the RTW. |
There was a problem hiding this comment.
Each point must describe an instruction. This point contains only information, which means it would be better located in an info (or equivalent) box.
| @@ -104,15 +136,6 @@ How to add a recipe to the |RTW| | |||
| #. Run the |RTW| again, as detailed in the :ref:`quick_start_guide`; the | |||
There was a problem hiding this comment.
Won't this be the first time the RTW is run now?
Description
Before you get started
Checklist
It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.
To help with the number of pull requests: