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

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. jj-vcs#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.
ilyagr · Feb 9, 2024 · 12c85ba · 12c85ba
1 parent 75d2bcf
commit 12c85ba
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 1 deletion.
diff --git a/cli/tests/[email protected] b/cli/tests/[email protected]
@@ -3,6 +3,8 @@ 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"
 ---
 
+
+<!-- BEGIN MARKDOWN-->
 !!! warning
 
     This CLI reference is experimental. It is automatically generated, but

diff --git a/cli/tests/test_generate_md_cli_help.rs b/cli/tests/test_generate_md_cli_help.rs
@@ -17,6 +17,8 @@ use insta::assert_snapshot;
 use crate::common::TestEnvironment;
 
 const PREAMBLE: &str = r#"
+
+<!-- BEGIN MARKDOWN-->
 !!! warning
 
     This CLI reference is experimental. It is automatically generated, but

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,16 @@
+<!-- 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
+ -->
+
+ <!-- TODO/BUG: The include-markdown plugin does not seem to work
+  --- for offline docs ("offline" plugin for MkDocs Material)
+  --- Cc: https://github.com/squidfunk/mkdocs-material/issues/6749
+  --->
+
+{%
+  include-markdown "../cli/tests/[email protected]"
+  rewrite-relative-urls=false
+  start="<!-- BEGIN MARKDOWN-->"
+%}
+
diff --git a/mkdocs-offline.yml b/mkdocs-offline.yml
@@ -2,6 +2,8 @@
 # your file system. To use, run:
 #      poetry run -- mkdocs build -f mkdocs-offline.yml
 INHERIT: 'mkdocs.yml'
+# TODO: The CLI reference is not currently generated correctly
+# https://github.com/squidfunk/mkdocs-material/issues/6749
 plugins:
     - offline
 # Turns out the `offline` plugin forces the following