Improve docs for CLI commands (#32)

* 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>

Author: kelly-sovacool

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)
 

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.

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')
 ```

src/ccbr_tools/__main__.py

@@ -16,15 +16,15 @@
 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()]
 )
 
 
 @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
 

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