From 437ea3cbeabdcd45b8016490e028fceeca7c3427 Mon Sep 17 00:00:00 2001
From: Drew De Ponte <cyphactor@gmail.com>
Date: Sat, 14 Oct 2023 23:03:44 -0400
Subject: [PATCH] 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.lock | 17 +++++++++++++++++
 Cargo.toml |  3 ++-
 build.rs   | 32 ++++++++++++++++++++++++++++++--
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 8b2e403..364410b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -533,6 +533,16 @@ version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cd7cc57abe963c6d3b9d8be5b06ba7c8957a930305ca90304f24ef040aa6f961"
 
+[[package]]
+name = "clap_mangen"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b44f35c514163027542f7147797ff930523eea288e03642727348ef1a9666f6b"
+dependencies = [
+ "clap",
+ "roff",
+]
+
 [[package]]
 name = "colorchoice"
 version = "1.0.0"
@@ -1069,6 +1079,7 @@ dependencies = [
  "ansi_term",
  "clap",
  "clap_complete",
+ "clap_mangen",
  "git2",
  "gpgme",
  "homedir",
@@ -1830,6 +1841,12 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "roff"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b833d8d034ea094b1ea68aa6d5c740e0d04bad9d16568d08ba6f76823a114316"
+
 [[package]]
 name = "rpassword"
 version = "7.2.0"
diff --git a/Cargo.toml b/Cargo.toml
index d4b8bbc..48a2ea9 100644
--- a/Cargo.toml
+++ b/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 = []
diff --git a/build.rs b/build.rs
index da03a86..3113a2f 100644
--- a/build.rs
+++ b/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(())
 }