search

ESMValGroup / ESMValTool

ESMValTool: A community diagnostic and performance metrics tool for routine evaluation of Earth system models in CMIP
https://www.esmvaltool.org
Apache License 2.0
210 stars 122 forks source link

Add how to add a recipe documentation #3614

Closed mo-gill closed 1 week ago

mo-gill commented 1 month ago

Description

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

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.

mo-gill commented 1 month ago

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 commented 1 month ago

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? 🤔

  1. 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).

  1. 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.)

  1. 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 commented 1 month ago

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.

mo-gill commented 1 month ago

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 commented 1 week ago

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