Fix doc generator to avoid incorrect check (#720)

The `reference/_generate.py` script was incorrectly filtering out
commands which did not have the `adoc_skip` attribute. This attribute
was actually removed in #713 , and the check therefore filters out
*all* commands.

To remedy:
- fix the check
- add logging to the doc generator to help identify issues in the
  future
- add a quick `--debug` flag which is used in CI to ensure that we get
  detailed output from the doc build

Author: sirosen

.github/workflows/docs.yaml

@@ -18,7 +18,7 @@ jobs:
           python -m pip install -e .
       - name: Generate Autodoc
         run: |
-          ./reference/_generate.py
+          ./reference/_generate.py --debug
           # bundle as tarball without the _generate.py script or .gitignore
           # use `-h` to dereference the changelog link
           tar --exclude "*.py" --exclude '.gitignore' -czf cli-reference.tar.gz -h reference/

reference/_generate.py

@@ -3,6 +3,8 @@
 
 based originally on click-man, but significantly specialized for the globus-cli
 """
+import argparse
+import logging
 import os
 import textwrap
 import time
@@ -16,6 +18,8 @@
 CLI = load_entry_point("globus-cli", "console_scripts", "globus")
 TARGET_DIR = os.path.dirname(__file__)
 
+log = logging.getLogger(__name__)
+
 try:
     # try to fetch last release date
     last_release = requests.get(
@@ -126,9 +130,11 @@ def __str__(self):
 
 def write_pages():
     for ctx in iter_all_commands():
-        if not isinstance(ctx.command, click.Group) and not getattr(
-            ctx.command, "adoc_skip", True
-        ):
+        log.debug("write_pages() handling: '%s'", ctx.command_path)
+        if not isinstance(ctx.command, click.Group):
+            log.info(
+                "write_pages() identified non-group command: '%s'", ctx.command_path
+            )
             cmd_name = ctx.command_path.replace(" ", "_")[len("globus_") :]
             path = os.path.join(TARGET_DIR, cmd_name + ".adoc")
             with open(path, "w") as f:
@@ -160,6 +166,21 @@ def generate_index():
                 f.write(ctx.command.get_short_help_str() + "\n\n")
 
 
-if __name__ == "__main__":
+def main():
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("--debug", help="enable debug logging", action="store_true")
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.INFO)
+
     write_pages()
     generate_index()
+
+
+if __name__ == "__main__":
+    main()

tox.ini

@@ -68,7 +68,7 @@ commands = mypy src/
 [testenv:reference]
 whitelist_externals = find
 commands_pre = find reference/ -name "*.adoc" -type f -delete
-commands = python ./reference/_generate.py
+commands = python ./reference/_generate.py {posargs}
 
 [testenv:twine-check]
 skip_install = true