#40: Add CLI help doc

mtkennerly · Nov 19, 2023 · 1df4be5 · 1df4be5
1 parent 6f774da
commit 1df4be5
Show file tree

Hide file tree

Showing 4 changed files with 205 additions and 21 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,6 +8,11 @@ Use the latest version of Rust.
   pip install --user pre-commit
   pre-commit install
   ```
+* Generate docs (requires Python):
+  ```
+  pip install --user invoke
+  invoke docs
+  ```
 
 ## Release
 Commands assume you are using [Git Bash](https://git-scm.com) on Windows:

diff --git a/README.md b/README.md
@@ -86,27 +86,7 @@ about Windows service user accounts can be found [here](https://stackoverflow.co
   ```
 
 ## CLI
-Below is the top-level help output (from `shawl --help`).
-For help with specific subcommands, you can add the command name (e.g., `shawl add --help`).
-
-```console
-$ shawl --help
-Wrap arbitrary commands as Windows services
-
-USAGE:
-    shawl.exe
-    shawl.exe <SUBCOMMAND>
-
-FLAGS:
-    -h, --help       Prints help information
-    -V, --version    Prints version information
-
-SUBCOMMANDS:
-    add     Add a new service
-    help    Prints this message or the help of the given subcommand(s)
-    run     Run a command as a service; only works when launched by the
-            Windows service manager
-```
+You can view the command line help text in [docs/cli.md](./docs/cli.md).
 
 ## Development
 Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,165 @@
+This is the raw help text for the command line interface.
+
+## `--help`
+```
+shawl
+Wrap arbitrary commands as Windows services
+
+USAGE:
+    shawl.exe
+    shawl.exe <SUBCOMMAND>
+
+OPTIONS:
+    -h, --help    Print help information
+
+SUBCOMMANDS:
+    add     Add a new service
+    help    Print this message or the help of the given subcommand(s)
+    run     Run a command as a service; only works when launched by the
+                Windows service manager
+```
+
+## `add --help`
+```
+shawl.exe-add
+Add a new service
+
+USAGE:
+    shawl.exe add [OPTIONS] --name <NAME> [--] <COMMAND>...
+
+ARGS:
+    <COMMAND>...    Command to run as a service
+
+OPTIONS:
+        --cwd <path>
+            Working directory in which to run the command. You may provide a
+            relative path, and it will be converted to an absolute one
+
+        --dependencies <DEPENDENCIES>
+            Other services that must be started first (comma-separated)
+
+        --env <ENV>
+            Additional environment variable in the format 'KEY=value'
+            (repeatable)
+
+    -h, --help
+            Print help information
+
+        --log-dir <path>
+            Write log file to a custom directory. This directory will be created
+            if it doesn't exist
+
+        --name <NAME>
+            Name of the service to create
+
+        --no-log
+            Disable all of Shawl's logging
+
+        --no-log-cmd
+            Disable logging of output from the command running as a service
+
+        --no-restart
+            Never restart the command regardless of the exit code
+
+        --pass <codes>
+            Exit codes that should be considered successful (comma-separated)
+            [default: 0]
+
+        --pass-start-args
+            Append the service start arguments to the command
+
+        --path <PATH>
+            Additional directory to add to the PATH environment variable
+            (repeatable)
+
+        --priority <PRIORITY>
+            Process priority of the command to run as a service [possible
+            values: realtime, high, above-normal, normal, below-normal, idle]
+
+        --restart
+            Always restart the command regardless of the exit code
+
+        --restart-if <codes>
+            Restart the command if the exit code is one of these
+            (comma-separated)
+
+        --restart-if-not <codes>
+            Restart the command if the exit code is not one of these
+            (comma-separated)
+
+        --stop-timeout <ms>
+            How long to wait in milliseconds between sending the wrapped process
+            a ctrl-C event and forcibly killing it [default: 3000]
+```
+
+## `run --help`
+```
+shawl.exe-run
+Run a command as a service; only works when launched by the Windows service
+manager
+
+USAGE:
+    shawl.exe run [OPTIONS] [--] <COMMAND>...
+
+ARGS:
+    <COMMAND>...    Command to run as a service
+
+OPTIONS:
+        --cwd <path>
+            Working directory in which to run the command. Must be an absolute
+            path
+
+        --env <ENV>
+            Additional environment variable in the format 'KEY=value'
+            (repeatable)
+
+    -h, --help
+            Print help information
+
+        --log-dir <path>
+            Write log file to a custom directory. This directory will be created
+            if it doesn't exist
+
+        --name <NAME>
+            Name of the service; used in logging, but does not need to match
+            real name [default: Shawl]
+
+        --no-log
+            Disable all of Shawl's logging
+
+        --no-log-cmd
+            Disable logging of output from the command running as a service
+
+        --no-restart
+            Never restart the command regardless of the exit code
+
+        --pass <codes>
+            Exit codes that should be considered successful (comma-separated)
+            [default: 0]
+
+        --pass-start-args
+            Append the service start arguments to the command
+
+        --path <PATH>
+            Additional directory to add to the PATH environment variable
+            (repeatable)
+
+        --priority <PRIORITY>
+            Process priority of the command to run as a service [possible
+            values: realtime, high, above-normal, normal, below-normal, idle]
+
+        --restart
+            Always restart the command regardless of the exit code
+
+        --restart-if <codes>
+            Restart the command if the exit code is one of these
+            (comma-separated)
+
+        --restart-if-not <codes>
+            Restart the command if the exit code is not one of these
+            (comma-separated)
+
+        --stop-timeout <ms>
+            How long to wait in milliseconds between sending the wrapped process
+            a ctrl-C event and forcibly killing it [default: 3000]
+```
diff --git a/tasks.py b/tasks.py
@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from invoke import task
+
+
+@task
+def docs(ctx):
+    docs = Path(__file__).parent / "docs"
+    cli = docs / "cli.md"
+
+    commands = [
+        "--help",
+        "add --help",
+        "run --help",
+    ]
+
+    lines = [
+        "This is the raw help text for the command line interface.",
+    ]
+    for command in commands:
+        output = ctx.run(f"cargo run -- {command}")
+        lines.append("")
+        lines.append(f"## `{command}`")
+        lines.append("```")
+        for line in output.stdout.splitlines():
+            lines.append(line.rstrip())
+        lines.append("```")
+
+    if not docs.exists():
+        docs.mkdir()
+    cli.unlink()
+    with cli.open("a") as f:
+        for line in lines:
+            f.write(line + "\n")