Adding updocs cli command for access to documentation

docs/getting_started.md

@@ -19,7 +19,7 @@ started you probably want to clone the git repo to get an example playbook:
 This should produce a list of available playbooks, similar to:
 
     usage: up [--help] [--up-full-traceback] [--up-list-playbooks] [--up-debug]
-           [--up-docs [DOCS_ARG]] [playbook]
+           [playbook]
 
     Available playbooks:
       - new-uplaybook (.uplaybooks/new-uplaybook)

docs/running.md

@@ -5,7 +5,7 @@
 Running "up" will list available playbooks and their descriptions:
 
     $ up
-    usage: up [--help] [--up-full-traceback] [--up-list-playbooks] [--up-debug] [--up-docs [DOCS_ARG]] [playbook]
+    usage: up [--help] [--up-full-traceback] [--up-list-playbooks] [--up-debug] [playbook]
 
     Available playbooks:
       - install-apache-module (.uplaybooks/install-apache-module)
@@ -37,17 +37,17 @@ arguments it takes:
 
 ## Getting Task Help
 
-Run `up --up-docs module.task` to get help about a task:
+Run `updocs module.task` to get help about a task:
 
-    $ up --up-docs fs.cp
+    $ updocs fs.cp
     # fs.cp
 
     Copy the `src` file to `dst`, optionally templating the contents in `src`.
     [...]
 
-Or to get a list of tasks in a module, specify `up --up-docs module`
+Or to get a list of tasks in a module, specify `updocs module`
 
-    $ up --up-docs fs
+    $ updocs fs
     Filesystem Related Tasks
 
     This module contains uPlaybook tasks that are related to file system operations.

docs/tutorial.md

@@ -141,15 +141,15 @@ fs.builder(defaults=Item(owner="headscale", group="headscale", mode="a=-,ug+rwX"
 
 ## Reading Docs
 
-How do you know what tasks and arguments are available?  uPlaybook includes an "--up-docs"
-argument that will display documentation:
+How do you know what tasks and arguments are available?  uPlaybook includes an "updocs"
+command that will display documentation:
 
 ```shell
-$ up --up-docs
+$ updocs
 [lists available modules]
 $ up --up-doc fs
 [lists available "fs" tasks]
-$ up --up-docs fs.
+$ updocs fs.
 # fs.ln
 
     Create a link from `src` to `path`.
@@ -401,7 +401,7 @@ You get the following output when running uPlaybook:
 
 ```bash
 $ up
-usage: up [--help] [--up-full-traceback] [--up-list-playbooks] [--up-debug] [--up-docs [DOCS_ARG]] [playbook]
+usage: up [--help] [--up-full-traceback] [--up-list-playbooks] [--up-debug] [playbook]
 
 Available playbooks:
   - new_blog.pb (.)

pyproject.toml

@@ -22,3 +22,4 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry.scripts]
 up = "uplaybook.cli:cli"
+updocs = "uplaybook.cli:updocs"

uplaybook/cli.py

@@ -47,11 +47,11 @@ def find_updocs(name: str) -> str:
     """
     Given a module/task name, return the docstring for it.
 
-    This iterates over the various options for how a "--up-docs" may be requested and returns
+    This iterates over the various options for how a "updocs" may be requested and returns
     the first appropriate docstring found.
 
     Args:
-        name: The "--up-docs" document to find.
+        name: The "updocs" document to find.
 
     Returns:
         The associated updoc.
@@ -124,6 +124,29 @@ def display_docs(name: str) -> None:
     pydoc.pager(re.sub(r"#\w+", "", docs).rstrip())
 
 
+def updocs():
+    """
+    The CLI entry-point for the `updocs` command.
+    """
+    parser = argparse.ArgumentParser(
+        prog="updocs",
+        description="Display help documentation for `up`, run with no arguments for overview.",
+        add_help=True,
+    )
+
+    parser.add_argument(
+        "documentation",
+        type=str,
+        nargs="?",
+        default="__main__",
+        help="What documentation display, usually a module or task name.  If omitted, an "
+        "overview is displayed.",
+    )
+    args = parser.parse_args()
+    display_docs(args.documentation)
+    sys.exit(0)
+
+
 class UpArgumentParser(argparse.ArgumentParser):
     """Wrapper so that "up", when run with no arguments, lists available playbooks."""
 
@@ -276,15 +299,6 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Display the version and exit?",
     )
-    parser.add_argument(
-        "--up-docs",
-        type=str,
-        nargs="?",
-        const="__main__",
-        default=None,
-        dest="docs_arg",
-        help="Display documentation, if an optional value is given the help for that component will be displayed.",
-    )
     parser.add_argument(
         "playbook", type=str, nargs="?", default=None, help="Name of the playbook."
     )
@@ -304,9 +318,6 @@ def parse_args() -> argparse.Namespace:
             parser.print_help()
             sys.exit(0)
         remaining_args.insert(0, "--help")
-    if args.docs_arg:
-        display_docs(args.docs_arg)
-        sys.exit(0)
 
     if not args.playbook:
         parser.print_usage()