From a66bba690cb3833013cb57b686834871ee7e7dd0 Mon Sep 17 00:00:00 2001
From: "Joshua A. Anderson" <joaander@umich.edu>
Date: Thu, 5 Dec 2024 12:16:17 -0500
Subject: [PATCH] Document show jobs.

---
 doc/src/SUMMARY.md       |  1 +
 doc/src/row/show/jobs.md | 59 ++++++++++++++++++++++++++++++++++++++++
 doc/src/row/submit.md    |  2 +-
 src/cli.rs               | 25 ++++++++++++++++-
 4 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100644 doc/src/row/show/jobs.md

diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
index 9ae989f..a6c6535 100644
--- a/doc/src/SUMMARY.md
+++ b/doc/src/SUMMARY.md
@@ -36,6 +36,7 @@
   - [show](row/show/index.md)
     - [show status](row/show/status.md)
     - [show directories](row/show/directories.md)
+    - [show jobs](row/show/jobs.md)
     - [show cluster](row/show/cluster.md)
     - [show launchers](row/show/launchers.md)
   - [scan](row/scan.md)
diff --git a/doc/src/row/show/jobs.md b/doc/src/row/show/jobs.md
new file mode 100644
index 0000000..479faa8
--- /dev/null
+++ b/doc/src/row/show/jobs.md
@@ -0,0 +1,59 @@
+# show jobs
+
+Usage:
+```bash
+row show jobs [OPTIONS] [DIRECTORIES]
+```
+
+`row show jobs` lists submitted jobs that execute a matching action on any of the
+provided directories.
+
+## `[DIRECTORIES]`
+
+List jobs that execute an action on one or more of the given directories. By default,
+**row** shows jobs executing an action on any directory.
+
+Pass a single `-` to read the directories from stdin (separated by newlines):
+```bash
+echo "dir1" | row show jobs [OPTIONS] -
+```
+
+## `[OPTIONS]`
+
+### `--action`
+
+(also: `-a`)
+
+Set `--action <pattern>` to show only jobs that mach the given pattern by name.
+By default, **row** shows jobs executing any action. `<pattern>` is a wildcard pattern.
+
+### `--no-header`
+
+Hide the header in the output.
+
+### `--short`
+
+Show only the job IDs.
+
+## Examples
+
+* Show all jobs:
+  ```bash
+  row show jobs
+  ```
+* Show jobs that execute actions on any of the given directories:
+  ```bash
+  row show jobs directory1 directory
+  ```
+* Show jobs that execute the action 'one':
+  ```bash
+  row show jobs --action one
+  ```
+* Show jobs that execute an action starting with 'analyze':
+  ```bash
+  row show jobs --action 'analyze*'
+  ```
+* Cancel SLURM jobs executing action 'two':
+  ```bash
+  row show jobs --action two --short | xargs scancel
+  ```
diff --git a/doc/src/row/submit.md b/doc/src/row/submit.md
index b332501..c16b940 100644
--- a/doc/src/row/submit.md
+++ b/doc/src/row/submit.md
@@ -24,7 +24,7 @@ the entire workspace.
 
 (also: `-a`)
 
-Set `--action <pattern>` to choose which actions to display by name. By default, **row**
+Set `--action <pattern>` to choose which actions to submit by name. By default, **row**
 submits the eligible jobs of all actions. `<pattern>` is a wildcard pattern.
 
 ### `--dry-run`
diff --git a/src/cli.rs b/src/cli.rs
index e2f7579..d758f5d 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -194,7 +194,30 @@ pub enum ShowCommands {
 
     /** Show submitted jobs.
 
-    TODO.
+    `row show jobs` lists submitted jobs that execute a matching action on
+    any of the provided directories.
+
+    EXAMPLES
+
+    * Show all jobs:
+
+      row show jobs
+
+    * Show jobs that execute actions on any of the given directories:
+
+      row show jobs directory1 directory
+
+    * Show jobs that execute the action 'one':
+
+      row show jobs --action one
+
+    * Show jobs that execute an action starting with 'analyze':
+
+      row show jobs --action 'analyze*'
+
+    * Cancel SLURM jobs executing action 'two':
+
+      row show jobs --action two --short | xargs scancel
     */
     Jobs(jobs::Arguments),
 }