From a197409b2b9bd61c297c12207a2bd088c5c1a723 Mon Sep 17 00:00:00 2001
From: Ilya Grigoriev <ilyagr@users.noreply.github.com>
Date: Thu, 25 Jan 2024 18:35:28 -0800
Subject: [PATCH] cli: new `jj util markdown-help` outputs `jj help` for all
 commands

This uses the [`clap-markdown`] library. It's not very flexible, but seems to
work. Its implementation is not difficult. If needed, we could later
reimplement the part that iterates over all subcommands and have a different
output (e.g., the boring version of each help text inside its own code block,
or a different file per subcommand, or some fancy template in handlebars or
another rust-supported templating language). I don't want to do it right now,
though.

The library does turn out to have some annoying bugs, e.g.
https://github.com/ConnorGray/clap-markdown/pull/18, but I think that's not a
deal-braker.  The fix seems to be 3 lines; if the fix doesn't get merged soon, we
could vendor the library maybe?

[`clap-markdown`]: https://docs.rs/clap-markdown/latest/clap_markdown/
---
 Cargo.lock               | 10 ++++++++++
 Cargo.toml               |  1 +
 cli/Cargo.toml           |  1 +
 cli/src/commands/util.rs | 18 ++++++++++++++++++
 4 files changed, 30 insertions(+)

diff --git a/Cargo.lock b/Cargo.lock
index d08734ead6..9191f93fd0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -367,6 +367,15 @@ dependencies = [
  "clap_derive",
 ]
 
+[[package]]
+name = "clap-markdown"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "325f50228f76921784b6d9f2d62de6778d834483248eefecd27279174797e579"
+dependencies = [
+ "clap",
+]
+
 [[package]]
 name = "clap_builder"
 version = "4.4.18"
@@ -1578,6 +1587,7 @@ dependencies = [
  "cargo_metadata",
  "chrono",
  "clap",
+ "clap-markdown",
  "clap_complete",
  "clap_mangen",
  "config",
diff --git a/Cargo.toml b/Cargo.toml
index 6b5731e2e0..c6d4b86832 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -32,6 +32,7 @@ clap = { version = "4.4.18", features = [
     "string",
 ] }
 clap_complete = "4.4.9"
+clap-markdown = "0.1.3"
 clap_mangen = "0.2.10"
 chrono = { version = "0.4.33", default-features = false, features = [
     "std",
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
index f6b1ab76ab..241b95a88a 100644
--- a/cli/Cargo.toml
+++ b/cli/Cargo.toml
@@ -32,6 +32,7 @@ cargo_metadata = { workspace = true }
 [dependencies]
 chrono = { workspace = true }
 clap = { workspace = true }
+clap-markdown = { workspace = true }
 clap_complete = { workspace = true }
 clap_mangen = { workspace = true }
 config = { workspace = true }
diff --git a/cli/src/commands/util.rs b/cli/src/commands/util.rs
index 4c0d9c7cff..f1c790a5bd 100644
--- a/cli/src/commands/util.rs
+++ b/cli/src/commands/util.rs
@@ -29,6 +29,7 @@ pub(crate) enum UtilCommand {
     Completion(UtilCompletionArgs),
     Gc(UtilGcArgs),
     Mangen(UtilMangenArgs),
+    MarkdownHelp(UtilMarkdownHelp),
     ConfigSchema(UtilConfigSchemaArgs),
 }
 
@@ -79,6 +80,10 @@ pub(crate) struct UtilGcArgs {
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct UtilMangenArgs {}
 
+/// Print the CLI help for all subcommands in Markdown
+#[derive(clap::Args, Clone, Debug)]
+pub(crate) struct UtilMarkdownHelp {}
+
 /// Print the JSON schema for the jj TOML config format.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct UtilConfigSchemaArgs {}
@@ -93,6 +98,7 @@ pub(crate) fn cmd_util(
         UtilCommand::Completion(args) => cmd_util_completion(ui, command, args),
         UtilCommand::Gc(args) => cmd_util_gc(ui, command, args),
         UtilCommand::Mangen(args) => cmd_util_mangen(ui, command, args),
+        UtilCommand::MarkdownHelp(args) => cmd_util_markdownhelp(ui, command, args),
         UtilCommand::ConfigSchema(args) => cmd_util_config_schema(ui, command, args),
     }
 }
@@ -152,6 +158,18 @@ fn cmd_util_mangen(
     Ok(())
 }
 
+fn cmd_util_markdownhelp(
+    ui: &mut Ui,
+    command: &CommandHelper,
+    _args: &UtilMarkdownHelp,
+) -> Result<(), CommandError> {
+    // If we ever need more flexibility, the code of `clap_markdown` is simple and
+    // readable. We could reimplement the parts we need without trouble.
+    let markdown = clap_markdown::help_markdown_command(command.app()).into_bytes();
+    ui.stdout_formatter().write_all(&markdown)?;
+    Ok(())
+}
+
 fn cmd_util_config_schema(
     ui: &mut Ui,
     _command: &CommandHelper,