Use the generate CLI reference.

hooked-book/source/cli-reference.txt

@@ -0,0 +1,42 @@
+This file is automatically generated using the cli-reference subcommand.
+Use `cargo run -- cli-reference` to generate it.
+
+// ANCHOR: install
+$ hooked install --help
+Install Hooked into ".git/hooks"
+
+Usage: hooked install [OPTIONS]
+
+Options:
+      --overwrite        Overwrite existing files
+  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
+  -h, --help             Print help information
+  -V, --version          Print version information
+// ANCHOR_END: install
+// ANCHOR: run
+$ hooked run --help
+Manually run hooks
+
+Usage: hooked run [OPTIONS] <HOOK_TYPE>
+
+Arguments:
+  <HOOK_TYPE>  The hook type to run [possible values: pre-commit]
+
+Options:
+  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
+  -h, --help             Print help information
+  -V, --version          Print version information
+// ANCHOR_END: run
+// ANCHOR: uninstall
+$ hooked uninstall --help
+Remove installed hooks
+
+Usage: hooked uninstall [OPTIONS]
+
+Options:
+      --all              Remove hooks not installed by Hooked
+  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
+  -h, --help             Print help information
+  -V, --version          Print version information
+// ANCHOR_END: uninstall
+

hooked-book/source/cli/install.md

@@ -3,16 +3,7 @@
 The `install` command creates the scripts inside `.git/hooks`.
 
 ```sh
-$ hooked install --help
+{{#include ../cli-reference.txt:install}}
-Install Hooked into ".git/hooks"
-
-Usage: hooked install [OPTIONS]
-
-Options:
-      --overwrite        Overwrite existing files
-  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
-  -h, --help             Print help information
-  -V, --version          Print version information
 ```
 
 Below is the default script template that Hooked uses, where `hook_type` is the type of hook to run (like `pre-commit`) and `config_path` is the `general.config` field from the parsed configuration.

hooked-book/source/cli/run.md

@@ -2,17 +2,6 @@
 
 The `run` command manually runs configured hooks.
 
-```
+```sh
-$ hooked run --help
+{{#include ../cli-reference.txt:run}}
-Manually run hooks
-
-Usage: hooked run [OPTIONS] <HOOK_TYPE>
-
-Arguments:
-  <HOOK_TYPE>  The hook type to run [possible values: pre-commit]
-
-Options:
-  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
-  -h, --help             Print help information
-  -V, --version          Print version information
 ```

hooked-book/source/cli/uninstall.md

@@ -3,16 +3,7 @@
 The `uninstall` command removes script files inside `.git/hooks`.
 
 ```sh
-hooked uninstall --help
+{{#include ../cli-reference.txt:uninstall}}
-Remove installed hooks
-
-Usage: hooked uninstall [OPTIONS]
-
-Options:
-      --all              Remove hooks not installed by Hooked
-  -c, --config <CONFIG>  Path to a Hooked configuration [default: Hooked.toml]
-  -h, --help             Print help information
-  -V, --version          Print version information
 ```
 
 By default Hooked will only remove scripts that have a `# Installed by Hooked.` line in them, using `--all` however will remove all script files.

hooked-cli/source/cli/cli_reference.rs

@@ -0,0 +1,51 @@
+//! The `cli-reference` subcommand, only available in debug mode.
+
+use std::{fs::write, process::Command, str};
+
+use {
+  color_eyre::Result,
+  hooked_config::Config,
+  tera::{Context, Tera},
+};
+
+use crate::cli::CliReferenceArgs;
+
+const REFERENCE_TEMPLATE: &str = include_str!("../templates/cli-reference.txt");
+
+/// The `cli-reference` subcommand.
+pub fn hooked_cli_reference(
+  _config: Config,
+  args: CliReferenceArgs,
+) -> Result<()> {
+  let out_path = if args.output.is_dir() {
+    args.output.join("cli-reference.txt")
+  } else {
+    args.output
+  };
+
+  let commands = {
+    let mut commands = vec![];
+    let commands_to_document = &["install", "run", "uninstall"];
+
+    for command_name in commands_to_document {
+      let output = Command::new("cargo")
+        .env("NO_COLOR", "1")
+        .args(&["run", "-q", "--", command_name, "--help"])
+        .output()
+        .unwrap();
+      let usage = str::from_utf8(&output.stdout).unwrap().trim().to_string();
+      commands.push((command_name.to_string(), usage))
+    }
+
+    commands
+  };
+
+  let mut context = Context::new();
+  context.insert("commands", &commands);
+  write(
+    &out_path,
+    Tera::one_off(REFERENCE_TEMPLATE, &context, false)?,
+  )?;
+
+  Ok(())
+}

hooked-cli/source/cli/mod.rs

@@ -4,10 +4,14 @@ use std::path::PathBuf;
 
 use clap::{Args as Arguments, Parser, Subcommand};
 
+#[cfg(debug_assertions)]
+mod cli_reference;
 mod install;
 mod run;
 mod uninstall;
 
+#[cfg(debug_assertions)]
+pub use cli_reference::hooked_cli_reference;
 pub use install::hooked_install;
 pub use run::hooked_run;
 pub use uninstall::hooked_uninstall;
@@ -37,6 +41,10 @@ pub enum MainSubcommands {
 
   /// Manually run hooks.
   Run(RunArgs),
+
+  #[cfg(debug_assertions)]
+  /// Generate the CLI reference file for the mdBook.
+  CliReference(CliReferenceArgs),
 }
 
 /// The `install` subcommand arguments.
@@ -62,3 +70,11 @@ pub struct RunArgs {
   #[clap(value_parser = crate::HOOK_TYPES)]
   pub hook_type: String,
 }
+
+/// The `cli-reference` subcommand arguments.
+#[derive(Debug, Arguments)]
+pub struct CliReferenceArgs {
+  /// Path where the CLI reference file should be generated.
+  #[clap(short, long, default_value = "hooked-book/source/")]
+  pub output: PathBuf,
+}

hooked-cli/source/main.rs

@@ -40,6 +40,11 @@ fn main() -> Result<()> {
     MainSubcommands::Run(sub_args) => {
       cli::hooked_run(config, sub_args.hook_type)?;
     }
+
+    #[cfg(debug_assertions)]
+    MainSubcommands::CliReference(sub_args) => {
+      cli::hooked_cli_reference(config, sub_args)?;
+    }
   }
 
   Ok(())

hooked-cli/source/templates/cli-reference.txt

@@ -0,0 +1,11 @@
+This file is automatically generated using the cli-reference subcommand.
+Use `cargo run -- cli-reference` to generate it.
+
+{% for command in commands %}
+{%- set name = command.0 -%}
+{%- set usage = command.1 -%}
+// ANCHOR: {{ name }}
+$ hooked {{ name }} --help
+{{ usage }}
+// ANCHOR_END: {{ name }}
+{% endfor %}