docs, CLI reference: use include-markdown instead of a symlink

The main goal is to avoid having a symlink in our source tree. Currently, there is no good way to work with the `jj` repo with `jj` on Windows. Currently `jj` just crashes with symlinks. This is being worked on, see e.g. #2939, but it will always depend on whether Developer Mode is enabled in Windows or whether symlinks are materialized as text files with symlinks. Finally, MkDocs has trouble following symlinks on Windows, so building docs wouldn't work there. Another advantage is that, previously, we were lucky that MkDocs treats `insta` header in `[email protected]` as a Markdown header and follows symlinks at all. Now, we no longer depend on that.
jj-vcs · Feb 12, 2024 · 16ec185 · 16ec185
1 parent 48d8396
commit 16ec185
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 13 deletions.
diff --git a/cli/tests/[email protected] b/cli/tests/[email protected]
@@ -3,12 +3,7 @@ source: cli/tests/test_generate_md_cli_help.rs
 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"
 ---
 
-!!! warning
-
-    This CLI reference is experimental. It is automatically generated, but
-    does not match the `jj help` output exactly.
-
-    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+<!-- BEGIN MARKDOWN-->
 
 # Command-Line Help for `jj`
 

diff --git a/cli/tests/test_generate_md_cli_help.rs b/cli/tests/test_generate_md_cli_help.rs
@@ -17,12 +17,7 @@ use insta::assert_snapshot;
 use crate::common::TestEnvironment;
 
 const PREAMBLE: &str = r#"
-!!! warning
-
-    This CLI reference is experimental. It is automatically generated, but
-    does not match the `jj help` output exactly.
-
-    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+<!-- BEGIN MARKDOWN-->
 
 "#;
 

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -0,0 +1,19 @@
+<!-- The contents of the CLI reference is auto-generated by a Rust test.
+ --- If `cargo insta` is installed, you can regenerate the CLI reference with:
+ ---      cargo insta test --accept --workspace -- test_generate
+ -->
+
+!!! warning
+
+    This CLI reference is experimental. It is automatically generated, but
+    does not match the `jj help` output exactly.
+
+    <!-- See also https://github.com/ConnorGray/clap-markdown/issues -->
+
+
+{%
+  include-markdown "../cli/tests/[email protected]"
+  rewrite-relative-urls=false
+  start="<!-- BEGIN MARKDOWN-->"
+%}
+