Merge #6776

6776: Include config into the manual r=matklad a=matklad

bors r+
🤖

Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>

crates/rust-analyzer/src/config.rs

@@ -637,6 +637,17 @@ macro_rules! _config_data {
                     },)*
                 ])
             }
+
+            #[cfg(test)]
+            fn manual() -> String {
+                manual(&[
+                    $({
+                        let field = stringify!($field);
+                        let ty = stringify!($ty);
+                        (field, ty, &[$($doc),*], $default)
+                    },)*
+                ])
+            }
         }
     };
 }
@@ -753,26 +764,54 @@ fn field_props(field: &str, ty: &str, doc: &[&str], default: &str) -> serde_json
     map.into()
 }
 
-#[test]
+#[cfg(test)]
-fn schema_in_sync_with_package_json() {
+fn manual(fields: &[(&'static str, &'static str, &[&str], &str)]) -> String {
+    fields
+        .iter()
+        .map(|(field, _ty, doc, default)| {
+            let name = field.replace("_", ".");
+            let name = format!("rust-analyzer.{} (default: `{}`)", name, default);
+            format!("{}::\n{}\n", name, doc.join(" "))
+        })
+        .collect::<String>()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+
+    use test_utils::project_dir;
+
+    use super::*;
+
+    #[test]
+    fn schema_in_sync_with_package_json() {
+        let s = Config::json_schema();
+        let schema = format!("{:#}", s);
+        let schema = schema.trim_start_matches('{').trim_end_matches('}');
+
+        let package_json = project_dir().join("editors/code/package.json");
+        let package_json = fs::read_to_string(&package_json).unwrap();
+
+        let p = remove_ws(&package_json);
+        let s = remove_ws(&schema);
+
+        assert!(p.contains(&s), "update config in package.json. New config:\n{:#}", schema);
+    }
+
+    #[test]
+    fn schema_in_sync_with_docs() {
+        let docs_path = project_dir().join("docs/user/generated_config.adoc");
+        let current = fs::read_to_string(&docs_path).unwrap();
+        let expected = ConfigData::manual();
+
+        if remove_ws(&current) != remove_ws(&expected) {
+            fs::write(&docs_path, expected).unwrap();
+            panic!("updated config manual");
+        }
+    }
+
     fn remove_ws(text: &str) -> String {
         text.replace(char::is_whitespace, "")
     }
-
-    let s = Config::json_schema();
-    let schema = format!("{:#}", s);
-    let schema = schema.trim_start_matches('{').trim_end_matches('}');
-
-    let package_json = std::env::current_dir()
-        .unwrap()
-        .ancestors()
-        .nth(2)
-        .unwrap()
-        .join("editors/code/package.json");
-    let package_json = std::fs::read_to_string(&package_json).unwrap();
-
-    let p = remove_ws(&package_json);
-    let s = remove_ws(&schema);
-
-    assert!(p.contains(&s), "update config in package.json. New config:\n{:#}", schema);
 }

docs/user/generated_config.adoc

@@ -0,0 +1,106 @@
+rust-analyzer.assist.importMergeBehaviour (default: `"full"`)::
+ The strategy to use when inserting new imports or merging imports.
+rust-analyzer.assist.importPrefix (default: `"plain"`)::
+ The path structure for newly inserted paths to use.
+rust-analyzer.callInfo.full (default: `true`)::
+ Show function name and docs in parameter hints.
+rust-analyzer.cargo.autoreload (default: `true`)::
+ Automatically refresh project info via `cargo metadata` on  Cargo.toml changes.
+rust-analyzer.cargo.allFeatures (default: `false`)::
+ Activate all available features.
+rust-analyzer.cargo.features (default: `[]`)::
+ List of features to activate.
+rust-analyzer.cargo.loadOutDirsFromCheck (default: `false`)::
+ Run `cargo check` on startup to get the correct value for package  OUT_DIRs.
+rust-analyzer.cargo.noDefaultFeatures (default: `false`)::
+ Do not activate the `default` feature.
+rust-analyzer.cargo.target (default: `null`)::
+ Compilation target (target triple).
+rust-analyzer.cargo.noSysroot (default: `false`)::
+ Internal config for debugging, disables loading of sysroot crates.
+rust-analyzer.checkOnSave.enable (default: `true`)::
+ Run specified `cargo check` command for diagnostics on save.
+rust-analyzer.checkOnSave.allFeatures (default: `null`)::
+ Check with all features (will be passed as `--all-features`).  Defaults to `rust-analyzer.cargo.allFeatures`.
+rust-analyzer.checkOnSave.allTargets (default: `true`)::
+ Check all targets and tests (will be passed as `--all-targets`).
+rust-analyzer.checkOnSave.command (default: `"check"`)::
+ Cargo command to use for `cargo check`.
+rust-analyzer.checkOnSave.noDefaultFeatures (default: `null`)::
+ Do not activate the `default` feature.
+rust-analyzer.checkOnSave.target (default: `null`)::
+ Check for a specific target. Defaults to  `rust-analyzer.cargo.target`.
+rust-analyzer.checkOnSave.extraArgs (default: `[]`)::
+ Extra arguments for `cargo check`.
+rust-analyzer.checkOnSave.features (default: `null`)::
+ List of features to activate. Defaults to  `rust-analyzer.cargo.features`.
+rust-analyzer.checkOnSave.overrideCommand (default: `null`)::
+ Advanced option, fully override the command rust-analyzer uses for  checking. The command should include `--message-format=json` or  similar option.
+rust-analyzer.completion.addCallArgumentSnippets (default: `true`)::
+ Whether to add argument snippets when completing functions.
+rust-analyzer.completion.addCallParenthesis (default: `true`)::
+ Whether to add parenthesis when completing functions.
+rust-analyzer.completion.postfix.enable (default: `true`)::
+ Whether to show postfix snippets like `dbg`, `if`, `not`, etc.
+rust-analyzer.completion.autoimport.enable (default: `true`)::
+ Toggles the additional completions that automatically add imports when completed.  Note that your client have to specify the `additionalTextEdits` LSP client capability to truly have this feature enabled.
+rust-analyzer.diagnostics.enable (default: `true`)::
+ Whether to show native rust-analyzer diagnostics.
+rust-analyzer.diagnostics.enableExperimental (default: `true`)::
+ Whether to show experimental rust-analyzer diagnostics that might  have more false positives than usual.
+rust-analyzer.diagnostics.disabled (default: `[]`)::
+ List of rust-analyzer diagnostics to disable.
+rust-analyzer.diagnostics.warningsAsHint (default: `[]`)::
+ List of warnings that should be displayed with info severity.\nThe  warnings will be indicated by a blue squiggly underline in code and  a blue icon in the problems panel.
+rust-analyzer.diagnostics.warningsAsInfo (default: `[]`)::
+ List of warnings that should be displayed with hint severity.\nThe  warnings will be indicated by faded text or three dots in code and  will not show up in the problems panel.
+rust-analyzer.files.watcher (default: `"client"`)::
+ Controls file watching implementation.
+rust-analyzer.hoverActions.debug (default: `true`)::
+ Whether to show `Debug` action. Only applies when  `#rust-analyzer.hoverActions.enable#` is set.
+rust-analyzer.hoverActions.enable (default: `true`)::
+ Whether to show HoverActions in Rust files.
+rust-analyzer.hoverActions.gotoTypeDef (default: `true`)::
+ Whether to show `Go to Type Definition` action. Only applies when  `#rust-analyzer.hoverActions.enable#` is set.
+rust-analyzer.hoverActions.implementations (default: `true`)::
+ Whether to show `Implementations` action. Only applies when  `#rust-analyzer.hoverActions.enable#` is set.
+rust-analyzer.hoverActions.run (default: `true`)::
+ Whether to show `Run` action. Only applies when  `#rust-analyzer.hoverActions.enable#` is set.
+rust-analyzer.hoverActions.linksInHover (default: `true`)::
+ Use markdown syntax for links in hover.
+rust-analyzer.inlayHints.chainingHints (default: `true`)::
+ Whether to show inlay type hints for method chains.
+rust-analyzer.inlayHints.maxLength (default: `null`)::
+ Maximum length for inlay hints.
+rust-analyzer.inlayHints.parameterHints (default: `true`)::
+ Whether to show function parameter name inlay hints at the call  site.
+rust-analyzer.inlayHints.typeHints (default: `true`)::
+ Whether to show inlay type hints for variables.
+rust-analyzer.lens.debug (default: `true`)::
+ Whether to show `Debug` lens. Only applies when  `#rust-analyzer.lens.enable#` is set.
+rust-analyzer.lens.enable (default: `true`)::
+ Whether to show CodeLens in Rust files.
+rust-analyzer.lens.implementations (default: `true`)::
+ Whether to show `Implementations` lens. Only applies when  `#rust-analyzer.lens.enable#` is set.
+rust-analyzer.lens.run (default: `true`)::
+ Whether to show `Run` lens. Only applies when  `#rust-analyzer.lens.enable#` is set.
+rust-analyzer.lens.methodReferences (default: `false`)::
+ Whether to show `Method References` lens. Only applies when  `#rust-analyzer.lens.enable#` is set.
+rust-analyzer.linkedProjects (default: `[]`)::
+ Disable project auto-discovery in favor of explicitly specified set  of projects.  \nElements must be paths pointing to Cargo.toml,  rust-project.json, or JSON objects in rust-project.json format.
+rust-analyzer.lruCapacity (default: `null`)::
+ Number of syntax trees rust-analyzer keeps in memory.
+rust-analyzer.notifications.cargoTomlNotFound (default: `true`)::
+ Whether to show `can't find Cargo.toml` error message.
+rust-analyzer.procMacro.enable (default: `false`)::
+ Enable Proc macro support, cargo.loadOutDirsFromCheck must be  enabled.
+rust-analyzer.runnables.overrideCargo (default: `null`)::
+ Command to be executed instead of 'cargo' for runnables.
+rust-analyzer.runnables.cargoExtraArgs (default: `[]`)::
+ Additional arguments to be passed to cargo for runnables such as  tests or binaries.\nFor example, it may be '--release'.
+rust-analyzer.rustcSource (default: `null`)::
+ Path to the rust compiler sources, for usage in rustc_private projects.
+rust-analyzer.rustfmt.extraArgs (default: `[]`)::
+ Additional arguments to rustfmt.
+rust-analyzer.rustfmt.overrideCommand (default: `null`)::
+ Advanced option, fully override the command rust-analyzer uses for  formatting.

docs/user/manual.adoc

@@ -263,6 +263,15 @@ If you get an error saying `No such file or directory: 'rust-analyzer'`, see the
 
 GNOME Builder 3.37.1 and newer has native `rust-analyzer` support. If the LSP binary is not available, GNOME Builder can install it when opening a Rust file.
 
+== Configration
+
+rust-analyzer is configured via LSP messages, which means that it's up to the editor to decide on the exact format and location of configuration files.
+Please consult your editor's documentation to learn how to configure LSP servers.
+
+This is the list of config options rust-analyzer supports:
+
+include::./generated_config.adoc[]
+
 == Non-Cargo Based Projects
 
 rust-analyzer does not require Cargo.

xtask/src/release.rs

@@ -54,9 +54,10 @@ https://github.com/sponsors/rust-analyzer[GitHub Sponsors].
 
         for &adoc in [
             "manual.adoc",
-            "generated_features.adoc",
             "generated_assists.adoc",
+            "generated_config.adoc",
             "generated_diagnostic.adoc",
+            "generated_features.adoc",
         ]
         .iter()
         {