mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2024-11-25 00:36:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

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

Browse source 
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 `cli-reference@.md.snap` as a Markdown header and follows symlinks at
all. Now, we no longer depend on that.
This commit is contained in:
Ilya Grigoriev 2024-02-07 12:09:39 -08:00
parent 48d839694e
commit 16ec185795
3 changed files with 21 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
cli/tests/cli-reference@.md.snap
View file

@ -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`

7
cli/tests/test_generate_md_cli_help.rs
View file

@ -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-->
"#;

1
docs/cli-reference.md
View file

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

19
docs/cli-reference.md Normal file
View file

@ -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/cli-reference@.md.snap"
rewrite-relative-urls=false
start="<!-- BEGIN MARKDOWN-->"
%}