docs: store output of jj util markdown-help, render it on the website

I am using a very hacky approach, using `insta` to generate the markdown help.
This is based on a lucky coincidence that `insta` chose to use a header
format for snapshot files that MkDocs interprets as a Markdown header (and
ignores).

I considered several other approaches, but I couldn't resist the facts that:

- This doesn't require new developers to install any extra tools or run any
extra commands.
- There is no need for a new CI check.
- There is no need to compile `jj` in the "Make HTML docs" GitHub action,
  which is currently very fast and cheap.

Downside: I'm not sure how well MkDocs will work on Windows, unless the
developer explicitly enables symbolic links (which IIUC is not trivial).

### Possible alternatives 

My next favorite approaches (which we could switch to later) would be:

#### `xtask`

Set up a CI check and a  [Cargo `xtask`]  so that `cargo xtask cli-help-to-md`
essentially runs `cargo run -- util markdown-help > docs/cli-reference.md` from
the project root.

Every developer would have to know to run `cargo xtask cli-help-to-md` if
they change the help text.

Eventually, we could have `cargo xtask preflight` that runs `cargo +nightly
fmt; cargo xtask cli-help-to-md; cargo nextest run`, or `cargo insta`.

#### Only generate markdown for CLI help when building the website, don't track it in Git.

I think that having the file in the repo will be nice to preview changes to
docs, and it'll allow people to consult the file on GitHub or in their repo.

The (currently) very fast job of building the website would now require
installing Rust and building `jj`. 

#### Same as the `xtask`, but use a shell script instead of an `xtask`

An `xtask` might seem like overkill, since it's Rust instead of a shell script.
However, I don't want this to be a shell script so that new contributors on
Windows can still easily run it ( since this will be necessary for the CI to
pass) without us having to support a batch file.

#### Cargo Alias

My first attempt was to set up a [cargo alias] to run this, but that doesn't
support redirection (so I had to change the `jj util` command to output to a
file) and, worse, is incapable of executing the command *in the project root*
regardless of where in the project the current directory is. Again, this seems
to be too inconvenient for a command that every new PR author would have to run
to pass CI.

Overall, this just seems a bit ugly. I did file
https://github.com/rust-lang/cargo/issues/13348, I'm not really sure that was
worthwhile, though.

**Aside:** For reference, the alias was:
    
```toml
# .cargo/config.toml
alias.gen-cli-reference = "run -p jj-cli -- util markdown-help docs/cli-reference.md"
```

### Non-alternatives 

#### Clap's new feature

`clap` recently obtained a similarly-sounding feature in
https://github.com/clap-rs/clap/pull/5206. However, it only prints short help
for subcommands and can't be triggered by an option AFAICT, so it won't help us
too much.

[Cargo `xtask`]: https://github.com/matklad/cargo-xtask
[cargo alias]: https://doc.rust-lang.org/cargo/reference/config.html#alias

.gitignore

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

cli/tests/test_generate_md_cli_help.rs

@@ -0,0 +1,39 @@
+// Copyright 2024 The Jujutsu Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use insta::assert_snapshot;
+
+use crate::common::TestEnvironment;
+
+pub mod common;
+
+#[test]
+fn test_generate_markdown_docs_in_docs_dir() {
+    let test_env = TestEnvironment::default();
+    let markdown_help = test_env.jj_cmd_success(test_env.env_root(), &["util", "markdown-help"]);
+    // Validate partial snapshot, redacting any lines nested 2+ indent levels.
+    insta::with_settings!({
+        snapshot_path => ".",
+        snapshot_suffix => ".md",
+        prepend_module_to_snapshot => false,
+        omit_expression => true,
+        description => "AUTO-GENERATED FILE, DO NOT EDIT. This cli reference is generated as an \
+                        `insta` snapshot. MkDocs follows they symlink from docs/cli-reference.md \
+                        to the snap. Unfortunately, `insta` unavoidably creates this header. Luckily, \
+                        MkDocs ignores the header since it has the same format as Markdown headers. \
+                        TODO: MkDocs may fail on Windows if symlinks are not enabled in the OS \
+                        settings",
+    },
+    { assert_snapshot!("cli-reference", markdown_help) });
+}

docs/cli-reference.md

@@ -0,0 +1 @@
+../cli/tests/cli-reference@.md.snap

mkdocs.yml

@@ -82,6 +82,8 @@ nav:
 
 - FAQ: 'FAQ.md'
 
+- "CLI Reference": 'cli-reference.md'
+
 - Concepts:
       - 'Working Copy': 'working-copy.md'
       - 'Branches': 'branches.md'