Setup man page generation from clap during build

Setup man page generation from clap during build so that we can
centralize the usage and in app docs within clap. This makes it much
easier to maintain rather than having to maintain two separate sets of
docs for usage that would naturally have a ton of overlap.

This relates to issue #239.

[changelog]
added: build time generation of man pages

<!-- ps-id: 5d43c4cd-f8e3-4b96-9d8a-7b62958ad285 -->

Cargo.toml

@@ -36,8 +36,9 @@ keyring = "2"
 tempfile = "3.3.0"
 
 [build-dependencies]
-clap = "4.4.6"
+clap = { version = "4.4.6", features = ["string"] }
 clap_complete = "4.4.3"
+clap_mangen = "0.2.14"
 
 [features]
 backup_cmd = []

build.rs

@@ -26,12 +26,40 @@ fn main() -> Result<(), Error> {
 
     let mut cmd = Cli::command();
 
+    // Generate Shell completions
     let _bash_completion_path =
         generate_to(Shell::Bash, &mut cmd, env!("CARGO_PKG_NAME"), &outdir)?;
     let _zsh_completion_path = generate_to(Shell::Zsh, &mut cmd, env!("CARGO_PKG_NAME"), &outdir)?;
 
-    // println!("cargo:warning=completion file is generated: {_bash_completion_path:?}");
-    // println!("cargo:warning=completion file is generated: {_zsh_completion_path:?}");
+    println!("cargo:warning=completion file is generated: {_bash_completion_path:?}");
+    println!("cargo:warning=completion file is generated: {_zsh_completion_path:?}");
+
+    // Generate primary man page
+    let man = clap_mangen::Man::new(cmd.clone());
+    let mut buffer: Vec<u8> = Default::default();
+    man.render(&mut buffer)?;
+    let _man_path = format!("{}/gps.1", outdir.to_str().unwrap());
+
+    std::fs::write(_man_path.as_str(), buffer)?;
+    println!("cargo:warning=man file is generated: {_man_path:?}");
+
+    // Generate subcommand man pages
+    let name = "gps";
+
+    for subcommand in cmd.get_subcommands() {
+        let subcommand_name = subcommand.get_name();
+        let subcommand_man_name = format!("{}-{}", name, &subcommand_name);
+        let mut buffer: Vec<u8> = Default::default();
+        let subcommand_man_name_clap_str_builder = clap::builder::Str::from(&subcommand_man_name);
+        let cmd_clone: clap::Command = subcommand
+            .clone()
+            .name(subcommand_man_name_clap_str_builder);
+        let man = clap_mangen::Man::new(cmd_clone);
+        man.render(&mut buffer)?;
+        let _man_path = format!("{}/{}.1", outdir.to_str().unwrap(), &subcommand_man_name);
+        std::fs::write(_man_path.as_str(), buffer)?;
+        println!("cargo:warning=man file is generated: {_man_path:?}");
+    }
 
     Ok(())
 }