From acbf0bc1f26599e9c3b6b9a188896f039fd0fc17 Mon Sep 17 00:00:00 2001
From: "Kelly Sovacool, PhD" <kelly-sovacool@users.noreply.github.com>
Date: Thu, 9 Jan 2025 14:02:15 -0500
Subject: [PATCH] Improve docs for CLI commands (#32)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: dynamic list of commands

* docs: strip ansi escape sequences from jobby help

* docs: improve gb2gtf help message

* chore: update CHANGELOG.md

* ci: 🤖 render readme

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 CHANGELOG.md               |  1 +
 README.md                  |  2 ++
 docs/cli.qmd               | 19 ++++++++++++++++---
 src/ccbr_tools/__main__.py |  5 +++--
 src/ccbr_tools/gb2gtf.py   |  8 +++++++-
 5 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43f19fb..9b5732f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@
   - fix docstrings rendering -- use Google style. (#25, @kelly-sovacool)
   - overhaul navigation structure of docs website. (#28, @kelly-sovacool)
   - style the website to follow FNL branding guidelines. (#30, @kelly-sovacool)
+  - miscellaneous minor improvements. (#32, @kelly-sovacool)
 - bug fixes:
   - include data files in package installation for `homologfinder`. (#31, @kelly-sovacool)
 
diff --git a/README.md b/README.md
index 4b0ded6..309e659 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,8 @@ ccbr_tools --help
 
       For more options, run: ccbr_tools [command] --help
 
+      https://ccbr.github.io/Tools/
+
     Options:
       -v, --version  Show the version and exit.
       -h, --help     Show this message and exit.
diff --git a/docs/cli.qmd b/docs/cli.qmd
index 5933813..105fa8e 100644
--- a/docs/cli.qmd
+++ b/docs/cli.qmd
@@ -9,11 +9,16 @@ subtitle: CLI utilities in CCBR Tools
 #| echo: false
 #| output: asis
 from ccbr_tools.shell import shell_run
+help_msg = shell_run("ccbr_tools --help")
 print("```")
-print(shell_run("ccbr_tools --help"))
+print(help_msg)
 print("```", end = '\n\n')
 
-for cmd in ('cite', 'send-email', 'version'):
+# get list of ccbr_tools commands from the help message
+help_lst = help_msg.split('\n\n')
+commands_idx = [idx for idx,ele in enumerate(help_lst) if ele.startswith('Commands:')][0]
+commands = [cmd.split()[0] for cmd in help_lst[commands_idx].split('\n')[1:]]
+for cmd in commands:
     print(f"### {cmd}", end = '\n\n')
     print("```")
     print(shell_run(f"ccbr_tools {cmd} --help"))
@@ -26,11 +31,19 @@ for cmd in ('cite', 'send-email', 'version'):
 ```{python}
 #| echo: false
 #| output: asis
+import re
 from ccbr_tools.pkg_util import get_project_scripts
+
+# https://stackoverflow.com/a/14693789/5787827
+ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
+
 for cmd in get_project_scripts():
     if cmd != 'ccbr_tools':
         print(f"### {cmd}", end = '\n\n')
         print("```")
-        print(shell_run(f"{cmd} --help"))
+        help_msg = shell_run(f"{cmd} --help")
+        if cmd == 'jobby':
+            help_msg = ansi_escape.sub('', help_msg)
+        print(help_msg)
         print("```", end = '\n\n')
 ```
diff --git a/src/ccbr_tools/__main__.py b/src/ccbr_tools/__main__.py
index aeb86d5..fe21390 100755
--- a/src/ccbr_tools/__main__.py
+++ b/src/ccbr_tools/__main__.py
@@ -16,7 +16,7 @@
 from .templates import use_quarto_ext, get_quarto_extensions
 
 
-all_commands = "All installed tools:\n" + "\n".join(
+all_scripts = "All installed tools:\n" + "\n".join(
     [f"  {cmd}" for cmd in get_project_scripts()]
 )
 
@@ -24,7 +24,7 @@
 @click.group(
     cls=CustomClickGroup,
     context_settings=dict(help_option_names=["-h", "--help"]),
-    epilog=all_commands,
+    epilog=all_scripts,
 )
 @click.version_option(get_version(), "-v", "--version", is_flag=True)
 def cli():
@@ -34,6 +34,7 @@ def cli():
     For more options, run:
     ccbr_tools [command] --help
 
+    https://ccbr.github.io/Tools/
     """
     pass
 
diff --git a/src/ccbr_tools/gb2gtf.py b/src/ccbr_tools/gb2gtf.py
index f6972fa..489fb84 100755
--- a/src/ccbr_tools/gb2gtf.py
+++ b/src/ccbr_tools/gb2gtf.py
@@ -21,10 +21,16 @@ def main():
         gb2gtf(sys.argv)
 
 
+usage_msg = """Convert GenBank files to GTF format.
+
+Usage: gb2gtf sequence.gb > sequence.gtf
+"""
+
+
 def check_args(args):
     valid_usage = True
     if len(args) < 2 or "-h" in args or "--help" in args:
-        print("Usage: gb2gtf sequence.gb > sequence.gtf")
+        print(usage_msg)
         valid_usage = False
     return valid_usage