From 1f52310238b4f3aa171e42f1c625ebd592fd9334 Mon Sep 17 00:00:00 2001
From: Ed Gillett <146008263+mo-gill@users.noreply.github.com>
Date: Thu, 23 May 2024 12:52:32 +0100
Subject: [PATCH] #3074: First draft of adding recipe documentation.

---
 .../doc/source/user_guide/adding_a_recipe.rst | 47 +++++++++++++++++++
 .../doc/source/user_guide/index.rst           |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/adding_a_recipe.rst

diff --git a/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/adding_a_recipe.rst b/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/adding_a_recipe.rst
new file mode 100644
index 0000000000..b255271c40
--- /dev/null
+++ b/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/adding_a_recipe.rst
@@ -0,0 +1,47 @@
+Adding a recipe to the |RTW|
+============================
+
+.. include:: ../common.txt
+
+* 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 workflows::
+
+    cylc stop "*"
+
+* Add the recipe to the ``[task parameters]`` section of the |RTW| ``flow.cylc``
+  workflow file (make sure to place it within the "fast" or "medium" category
+  depending on how long it took to run):
+
+* Run the workflow (it should fail)::
+
+    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 the KGO rootpath folder (/data/users/esmval/KGO)::
+
+    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>
+
+* 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.
diff --git a/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/index.rst b/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/index.rst
index 01359728e2..ef7e2081d3 100644
--- a/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/index.rst
+++ b/esmvaltool/utils/recipe_test_workflow/doc/source/user_guide/index.rst
@@ -7,3 +7,4 @@ User Guide
 
    quick_start
    workflow
+   adding_a_recipe