Publish CLI help on docs website

.gitignore

@@ -7,6 +7,7 @@ result
 # generated by the insta crate
 *.pending-snap
 *.snap*
+!cli/tests/[email protected]
 
 # Editor specific ignores
 .idea

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",

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 }

cli/src/commands/next.rs

@@ -31,24 +31,28 @@ use crate::ui::Ui;
 /// The command moves you to the next child in a linear fashion.
 ///
 ///
+/// ```
 /// D      D @
 /// |      |/
 /// C @ => C
 /// |/     |
 /// B      B
+/// ```
 ///
 ///
 /// If `--edit` is passed, it will move you directly to the child
 /// revision.
 ///
 ///
+/// ```
 /// D    D
 /// |    |
 /// C    C
 /// |    |
 /// B => @
 /// |    |
 /// @    A
+/// ```
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]
 pub(crate) struct NextArgs {

cli/src/commands/prev.rs

@@ -25,25 +25,26 @@ use crate::ui::Ui;
 ///
 /// The command moves you to the parent in a linear fashion.
 ///
-///
+/// ```
 /// D @  D
 /// |/   |
 /// A => A @
 /// |    | /
 /// B    B
-///
+/// ```
 ///
 /// If `--edit` is passed, it will move the working copy commit
 /// directly to the parent.
 ///
-///
+/// ```
 /// D @  D
 /// |/   |
 /// C => @
 /// |    |
 /// B    B
 /// |    |
 /// A    A
+/// ```
 // TODO(#2126): Handle multiple parents, e.g merges.
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]

cli/src/commands/rebase.rs

@@ -46,6 +46,7 @@ use crate::ui::Ui;
 /// your history like this (letters followed by an apostrophe are post-rebase
 /// versions):
 ///
+/// ```
 /// O           N'
 /// |           |
 /// | N         M'
@@ -57,6 +58,7 @@ use crate::ui::Ui;
 /// | K         | K
 /// |/          |/
 /// J           J
+/// ```
 ///
 /// With `-b`, the command rebases the whole "branch" containing the specified
 /// revision. A "branch" is the set of commits that includes:
@@ -71,6 +73,7 @@ use crate::ui::Ui;
 /// -d O` would transform your history like this (because `L` and `M` are on the
 /// same "branch", relative to the destination):
 ///
+/// ```
 /// O           N'
 /// |           |
 /// | N         M'
@@ -82,32 +85,37 @@ use crate::ui::Ui;
 /// | K         O
 /// |/          |
 /// J           J
+/// ```
 ///
 /// With `-r`, the command rebases only the specified revision onto the
 /// destination. Any "hole" left behind will be filled by rebasing descendants
 /// onto the specified revision's parent(s). For example, `jj rebase -r K -d M`
 /// would transform your history like this:
 ///
+/// ```
 /// M          K'
 /// |          |
 /// | L        M
 /// | |   =>   |
 /// | K        | L'
 /// |/         |/
 /// J          J
+/// ```
 ///
 /// Note that you can create a merge commit by repeating the `-d` argument.
 /// For example, if you realize that commit L actually depends on commit M in
 /// order to work (in addition to its current parent K), you can run `jj rebase
 /// -s L -d K -d M`:
 ///
+/// ```
 /// M          L'
 /// |          |\
 /// | L        M |
 /// | |   =>   | |
 /// | K        | K
 /// |/         |/
 /// J          J
+/// ```
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]
 #[command(group(ArgGroup::new("to_rebase").args(&["branch", "source", "revision"])))]

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,