jj / How jj util markdown-help works

How jj util markdown-help works

jj util markdown-help prints the help of every jj command as one Markdown document, the source of the online CLI reference.

On this page
  1. 1. Command-line surface
  2. 3. End-to-end flow
  3. 4. Core architecture touchpoints

In short: it hands the clap command tree to the clap-markdown crate and writes the result to stdout. Upstream's own test runs it and keeps the output as a snapshot that the docs site includes, so the published CLI reference is regenerated whenever a command's help changes.

The command is cmd_util_markdown_help. Its help text: "Print the CLI help for all subcommands in Markdown" (source). It is the MarkdownHelp variant of UtilCommand (source, dispatch).

1. Command-line surface

No arguments: UtilMarkdownHelp is empty (source). The global flags are on the CLI page.

3. End-to-end flow

jj util markdown-help: flow and its use in upstream's docs cmd_util_markdown_help passes command.app() to clap_markdown::help_markdown_command and writes the bytes to stdout. Upstream's test test_generate_markdown_docs_in_docs_dir runs the command, prefixes a marker, and stores the result as the insta snapshot cli-reference@.md.snap, which docs/cli-reference.md includes. cmd_util_markdown_help help_markdown_command(command.app()) test_generate_markdown_docs_in_docs_dir runs it, snapshots the output docs/cli-reference.md includes cli-reference@.md.snap

4. Core architecture touchpoints

PieceRole here
The clap command tree (command.app())The only input, so the Markdown always matches what jj help prints for the same binary (source).
clap-markdownPinned to an exact version, because a new version would change the snapshot (source).
cli-reference@.md.snapThe generated reference, marked "AUTO-GENERATED FILE, DO NOT EDIT" (source).
Repo, working copy, operation logNot touched (source).