From 64fa84746a5fc398cc71d591024a5e3fe6aa70e7 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sat, 3 Feb 2024 18:11:18 -0800 Subject: [PATCH] docs CLI reference: add a warning that it is experimental There are many minor bugs that are difficult to fix in the short-term. See also the commit message for a197409b2b --- cli/tests/cli-reference@.md.snap | 8 ++++++++ cli/tests/test_generate_md_cli_help.rs | 14 +++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap index 12065edbf..b042c4a1b 100644 --- a/cli/tests/cli-reference@.md.snap +++ b/cli/tests/cli-reference@.md.snap @@ -2,6 +2,14 @@ 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. + + + # Command-Line Help for `jj` This document contains the help content for the `jj` command-line program. diff --git a/cli/tests/test_generate_md_cli_help.rs b/cli/tests/test_generate_md_cli_help.rs index 3d3b1f851..ba7b46d86 100644 --- a/cli/tests/test_generate_md_cli_help.rs +++ b/cli/tests/test_generate_md_cli_help.rs @@ -18,10 +18,22 @@ use crate::common::TestEnvironment; pub mod common; +const PREAMBLE: &str = r#" +!!! warning + + This CLI reference is experimental. It is automatically generated, but + does not match the `jj help` output exactly. + + + +"#; + #[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"]); + let mut markdown_help = PREAMBLE.to_string(); + markdown_help + .push_str(&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 => ".",