From 6392dccd24a22b7a5cb7b1f88a444d723a4c3b3d Mon Sep 17 00:00:00 2001
From: David Peter <sharkdp@users.noreply.github.com>
Date: Fri, 23 May 2025 11:58:16 +0200
Subject: [PATCH] [ty] Add warning that docs are autogenerated (#18270)

## Summary

This is a practice I followed on previous projects. Should hopefully
further help developers who want to update the documentation.

The big downside is that it's annoying to see this *as a user of the
documentation* if you don't open the Markdown file in the browser. But
I'd argue that those files don't really follow the original Markdown
spirit anyway with all the inline HTML.
---
 crates/ruff_dev/src/generate_ty_cli_reference.rs | 1 +
 crates/ruff_dev/src/generate_ty_options.rs       | 4 ++++
 crates/ruff_dev/src/generate_ty_rules.rs         | 4 ++++
 crates/ty/docs/cli.md                            | 2 ++
 crates/ty/docs/configuration.md                  | 2 ++
 crates/ty/docs/rules.md                          | 2 ++
 6 files changed, 15 insertions(+)

diff --git a/crates/ruff_dev/src/generate_ty_cli_reference.rs b/crates/ruff_dev/src/generate_ty_cli_reference.rs
index c240e76537..58914d7414 100644
--- a/crates/ruff_dev/src/generate_ty_cli_reference.rs
+++ b/crates/ruff_dev/src/generate_ty_cli_reference.rs
@@ -80,6 +80,7 @@ fn generate() -> String {
 
     let mut parents = Vec::new();
 
+    output.push_str("<!-- WARNING: This file is auto-generated (cargo dev generate-all). Edit the doc comments in 'crates/ty/src/args.rs' if you want to change anything here. -->\n\n");
     output.push_str("# CLI Reference\n\n");
     generate_command(&mut output, &ty, &mut parents);
 
diff --git a/crates/ruff_dev/src/generate_ty_options.rs b/crates/ruff_dev/src/generate_ty_options.rs
index 1542e3e45d..b764278b21 100644
--- a/crates/ruff_dev/src/generate_ty_options.rs
+++ b/crates/ruff_dev/src/generate_ty_options.rs
@@ -25,6 +25,10 @@ pub(crate) fn main(args: &Args) -> anyhow::Result<()> {
     let file_name = "crates/ty/docs/configuration.md";
     let markdown_path = PathBuf::from(ROOT_DIR).join(file_name);
 
+    output.push_str(
+        "<!-- WARNING: This file is auto-generated (cargo dev generate-all). Update the doc comments on the 'Options' struct in 'crates/ty_project/src/metadata/options.rs' if you want to change anything here. -->\n\n",
+    );
+
     generate_set(
         &mut output,
         Set::Toplevel(Options::metadata()),
diff --git a/crates/ruff_dev/src/generate_ty_rules.rs b/crates/ruff_dev/src/generate_ty_rules.rs
index d28a2feafb..cf1f3f8aaa 100644
--- a/crates/ruff_dev/src/generate_ty_rules.rs
+++ b/crates/ruff_dev/src/generate_ty_rules.rs
@@ -56,6 +56,10 @@ fn generate_markdown() -> String {
 
     let mut output = String::new();
 
+    let _ = writeln!(
+        &mut output,
+        "<!-- WARNING: This file is auto-generated (cargo dev generate-all). Edit the lint-declarations in 'crates/ty_python_semantic/src/types/diagnostic.rs' if you want to change anything here. -->\n"
+    );
     let _ = writeln!(&mut output, "# Rules\n");
 
     let mut lints: Vec<_> = registry.lints().iter().collect();
diff --git a/crates/ty/docs/cli.md b/crates/ty/docs/cli.md
index d5cfaa311b..40ef8cf651 100644
--- a/crates/ty/docs/cli.md
+++ b/crates/ty/docs/cli.md
@@ -1,3 +1,5 @@
+<!-- WARNING: This file is auto-generated (cargo dev generate-all). Edit the doc comments in 'crates/ty/src/args.rs' if you want to change anything here. -->
+
 # CLI Reference
 
 ## ty
diff --git a/crates/ty/docs/configuration.md b/crates/ty/docs/configuration.md
index 1d18d9d093..3efd6e541e 100644
--- a/crates/ty/docs/configuration.md
+++ b/crates/ty/docs/configuration.md
@@ -1,3 +1,5 @@
+<!-- WARNING: This file is auto-generated (cargo dev generate-all). Update the doc comments on the 'Options' struct in 'crates/ty_project/src/metadata/options.rs' if you want to change anything here. -->
+
 # Configuration
 #### `respect-ignore-files`
 
diff --git a/crates/ty/docs/rules.md b/crates/ty/docs/rules.md
index 6eac8f7408..40a2e2fa13 100644
--- a/crates/ty/docs/rules.md
+++ b/crates/ty/docs/rules.md
@@ -1,3 +1,5 @@
+<!-- WARNING: This file is auto-generated (cargo dev generate-all). Edit the lint-declarations in 'crates/ty_python_semantic/src/types/diagnostic.rs' if you want to change anything here. -->
+
 # Rules
 
 ## `byte-string-type-annotation`