Add how to add a recipe documentation

[mo-gill]

Description

Add instructions on how to add a recipe to the recipe test workflow, to the documentation

• Closes Add how to add a recipe documentation #3074

---

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.

• 🛠 This pull request has a descriptive title
• 🛠 Code is written according to the code quality guidelines

[mo-gill]

Hello @alistairsellar and @ehogan!

I have committed my first draft of this here 1f52310

I have some questions it would be helpful if you could address

1. Should we add instructions for what to do when the recipe throws an error that it needs the user to download missing data?

2. Do we need to run esmvaltool run locally first if we're getting the time/mem results from cylc review?

3. I haven't run ESMValTool on JASMIN myself so unsure how much detail to go into for this in the documentation?

4. Is kgo_rootpath site specific? (does it change between sites or is it always the same directory /data/users/esmval/KGO)?

Thanks

[ehogan]

Hello @alistairsellar and @ehogan!

I have committed my first draft of this here 1f52310

🥳

I have some questions it would be helpful if you could address

1. Should we add instructions for what to do when the recipe throws an error that it needs the user to download missing data?

Perhaps we could add a "Prerequisites" section that says "To follow these instructions, you must be able to successfully run the recipe you want to add to the RTW" or equivalent? 🤔

2. Do we need to run esmvaltool run locally first if we're getting the time/mem results from cylc review?

I think we need to run esmvaltool locally first to set the time and memory values in the first place, then I think we should get people to check Cylc Review after the first run to make sure the values aren't drastically different (and use the values from Cylc Review in the comment).

3. I haven't run ESMValTool on JASMIN myself so unsure how much detail to go into for this in the documentation?

I don't think it's necessary to go into any detail here, personally. (As mentioned under 1., I would argue that it would be expected that people can successfully run their recipe.)

4. Is kgo_rootpath site specific? (does it change between sites or is it always the same directory /data/users/esmval/KGO)?

Yes, it's defined in the site-specific files in the esmvaltool/utils/recipe_test_workflow/recipe_test_workflow/opt/ directory, see, e.g. esmvaltool/utils/recipe_test_workflow/recipe_test_workflow/opt/rose-suite-metoffice.conf file 😊

[alistairsellar]

Hello @alistairsellar and @ehogan!

I have committed my first draft of this here 1f52310

Great! Hope to take a look later today.

I agree with @ehogan's answers above. On 1 & 3, these instructions are for adding a working recipe to RTW, so fundamental problems running the recipe are out of scope.

[alistairsellar]

Great work - thanks @mo-gill!

A couple of suggestions from me, please.

[mo-gill]

Added pydata-sphinx-theme to the environment via the rtw-env.yml and the lock file in commit 8c82530, to fix the build errors in the GitHub workflow

[alistairsellar]

Thanks Ed - great work!

Outdated.

[ehogan]

Many thanks for your hard work on this @mo-gill! 🎉

[alistairsellar]

Great work @mo-gill! Great to have these instructions in place!