From d26fa618f13c343e862e434cb0d7c8c2bff16abf Mon Sep 17 00:00:00 2001
From: Abhaas Goyal <goyalabhaas@gmail.com>
Date: Tue, 5 Mar 2024 14:39:04 +1100
Subject: [PATCH] Add documentation related to CABLE local checkout and
 benchcab clean

---
 benchcab/cli.py                   | 10 ++++++++--
 docs/user_guide/config_options.md | 17 +++++++++++++++++
 docs/user_guide/index.md          |  6 ++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/benchcab/cli.py b/benchcab/cli.py
index 666727c..76dbbfb 100644
--- a/benchcab/cli.py
+++ b/benchcab/cli.py
@@ -231,12 +231,18 @@ def generate_parser(app: Benchcab) -> argparse.ArgumentParser:
         help="Cleanup files created by running benchcab.",
         description="""Removes src/ and runs/ directories, along with log files in the 
         project root directory. The user has to specify which stage of files to remove 
-        via \{all, realisations, submissions\} subcommand""",
+        via \{all, realisations, submissions\} subcommand.""",
         add_help=False,
     )
 
     parser_clean.add_argument(
-        "clean_option", choices=["all", "realisations", "submissions"]
+        "clean_option",
+        choices=["all", "realisations", "submissions"],
+        help="""Can be one of three options:
+
+        submissions: deletes src/ and revision log files
+        realisations: deletes runs/ and benchmark submission files
+        all: deletes in both stages of submissions and realisations""",
     )
 
     parser_clean.set_defaults(func=app.clean)
diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md
index 9da6b5d..0f71cc4 100644
--- a/docs/user_guide/config_options.md
+++ b/docs/user_guide/config_options.md
@@ -352,6 +352,23 @@ realisations:
 
 : **Default:** URL of the [CABLE GitHub repository][cable-github], _optional key_. :octicons-dash-24: Specify the GitHub repository url to clone from when checking out the branch.
 
+#### [`local`](#+repo.local){ #+repo.local}
+
+Contains settings to specify CABLE checkouts on a local repository.
+
+This key is _optional_. No default.
+
+```yaml
+realisations:
+  - repo:
+      local:
+        path: /scratch/tm70/ab1234/CABLE
+```
+
+[`path`](#+repo.local.path){ #+repo.local.path}
+
+: **Default:** _required key, no default_. :octicons-dash-24: Specify the local checkout path of CABLE branch.
+
 ### [name](#name)
 
 : **Default:** base name of [branch_path](#+repo.svn.branch_path) if an SVN repository is given, for Git repositories the default is the branch name, _optional key_. :octicons-dash-24: An alias name used internally by `benchcab` for the branch. The `name` key also specifies the directory name of the source code when retrieving from SVN or GitHub.
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
index 23c836b..528f82c 100644
--- a/docs/user_guide/index.md
+++ b/docs/user_guide/index.md
@@ -91,6 +91,12 @@ The tool will follow the steps:
 3. Setup and launch a PBS job to run the flux site simulations in parallel. When `benchcab` launches the PBS job, it will print out the job ID to the terminal. You can check the status of the job with `qstat`. `benchcab` will not warn you when the simulations are over.
 4. Setup and run an ensemble of offline spatial runs using the [`payu`][payu-github] framework.
 
+!!! info
+    In case the code branches are already checked out before running Step (1) - `benchcab` will fail. This could happen on re-runs of `benchcab`. In that case, run `benchcab clean realisations` before the `checkout` step.
+
+!!! warning
+    It is dangerous to delete `src/` via `rm -rf`, since `src/` may contain symlinks to local directories that could also be affected. Use `benchcab clean realisations` instead, which would also delete unecessary log files like `rev_number-*.log`. 
+
 !!! tip "Expected output"
 
     You can see [an example of the expected output](expected_output.md) printed out to the screen by `benchcab run` to check if the tool has worked as expected.