Change the list of commands

- Remove the `check-links` command as it is now `show check-links`
- Add a `usage` command to display usage instead of cluttering the main help message
- Add a `show-failed [target]` command and change `show all` to `show` to unify syntax

bennettbot/job_configs.py

@@ -303,16 +303,15 @@
         "restricted": True,
         "description": "Report GitHub Actions workflow runs",
         "jobs": {
-            "check_links": {
-                "run_args_template": "python jobs.py show --target check-links",
-                "report_stdout": True,
-                "report_format": "blocks",
-            },
             "display_emoji_key": {
                 "run_args_template": "python jobs.py key",
                 "report_stdout": True,
                 "report_format": "blocks",
             },
+            "display_usage": {
+                "run_args_template": "python jobs.py usage",
+                "report_stdout": True,
+            },
             "show": {
                 "run_args_template": "python jobs.py show --target {target}",
                 "report_stdout": True,
@@ -324,44 +323,53 @@
                 "report_format": "blocks",
             },
             "show_failed": {
+                "run_args_template": "python jobs.py show --target {target} --skip-successful",
+                "report_stdout": True,
+                "report_format": "blocks",
+            },
+            "show_failed_all": {
                 "run_args_template": "python jobs.py show --target all --skip-successful",
                 "report_stdout": True,
                 "report_format": "blocks",
             },
         },
         "slack": [
-            {
-                "command": "check-links",
-                "help": "Summarise GitHub Actions workflow runs for link-checking workflows in website repos.",
-                "action": "schedule_job",
-                "job_type": "check_links",
-            },
             {
                 "command": "key",
                 "help": "Show the emoji key being used in the workflow summaries.",
                 "action": "schedule_job",
                 "job_type": "display_emoji_key",
             },
             {
-                "command": "show all",
+                "command": "usage",
+                "help": "Show help message for the `show [target]` and `show-failed [target]` commands.",
+                "action": "schedule_job",
+                "job_type": "display_usage",
+            },
+            {
+                "command": "show",
                 "help": "Summarise GitHub Actions workflow runs for repos in all organisations.",
                 "action": "schedule_job",
                 "job_type": "show_all",
             },
             {
                 "command": "show-failed",
-                "help": "Summarise GitHub Actions workflow runs for repos in all organisations, skipping repos whose runs are all successful.",
+                "help": "Summarise GitHub Actions workflow runs for repos in all organisations, but skips summarising repos whose runs are all successful.",
                 "action": "schedule_job",
-                "job_type": "show_failed",
+                "job_type": "show_failed_all",
             },
             {
                 "command": "show [target]",
-                # There is a line break in this help message because it will take two lines anyway and breaking here gives better readability.
-                "help": "Summarise GitHub Actions workflow runs for a given `target` organisation or repo, provided in the form of `org` or `org/repo`. \n(Note: `org` is limited to the following shorthands and their full names: `os (opensafely)`, `osc (opensafely-core)`, `bo (bennettoxford)`, `ebm (ebmdatalab)`.)",
+                "help": "Summarise GitHub Actions workflow runs for `target`. See `workflows usage` for valid `target` values.",
                 "action": "schedule_job",
                 "job_type": "show",
             },
-
+            {
+                "command": "show-failed [target]",
+                "help": "Same as `show [target]`, but skips summarising repos whose runs are all successful.",
+                "action": "schedule_job",
+                "job_type": "show_failed",
+            },
         ]
     },
     "techsupport": {

tests/workspace/test_workflows.py

@@ -203,6 +203,13 @@ def test_print_key():
     assert json.loads(jobs.get_text_blocks_for_key(None)) == blocks
 
 
+def test_print_usage():
+    usage_text = jobs.get_usage_text(None)
+    with pytest.raises(json.JSONDecodeError):
+        json.loads(usage_text)
+    assert usage_text.startswith("Below lists the behaviour for `show [target]`.")
+
+
 def test_all_as_target():
     args = jobs.get_command_line_parser().parse_args("show --target all".split())
 

workspace/workflows/jobs.py

@@ -402,6 +402,19 @@ def get_text_blocks_for_key(args) -> str:
     return json.dumps(blocks)
 
 
+def get_usage_text(args) -> str:
+    return "\n".join(
+        [
+            "Below lists the behaviour for `show [target]`. The behaviour for `show-failed [target]` is the same, but skips repos whose workflows are all successful.",
+            "`show [all]`: Summarise all repos, sectioned by team.",
+            "`show [org]`: Summarise all repos for a known organisation, which is limited to the following shorthands and their full names: `os (opensafely)`, `osc (opensafely-core)` or `ebm (ebmdatalab)`.",
+            "`show [repo]`: Report status for all workflows in a known repo (e.g. `show airlock`) or a repo in a known org (e.g. `show os/some-study-repo`).",
+            "`show check-links`: Summarise the status for the custom group of link-checking workflows.",
+            "To show a list of targets in the same command, provide a command-separated list (without spaces), e.g. `show os,osc` or `show airlock,ehrql`.",
+        ]
+    )
+
+
 def get_command_line_parser():
     parser = argparse.ArgumentParser()
     subparsers = parser.add_subparsers(required=True)
@@ -415,6 +428,10 @@ def get_command_line_parser():
     # Display key
     key_parser = subparsers.add_parser("key")
     key_parser.set_defaults(func=get_text_blocks_for_key)
+
+    # Display usage
+    usage_text_parser = subparsers.add_parser("usage")
+    usage_text_parser.set_defaults(func=get_usage_text)
     return parser