From cddea9d23ccef8b17ab8de704ee2e5c20af65c12 Mon Sep 17 00:00:00 2001 From: Lukas Wirth Date: Tue, 11 Jun 2024 11:40:18 +0200 Subject: [PATCH] Some better codeblocks --- docs/book/src/editor_features/README.md | 202 ++++++++-------- .../src/non_cargo_based_projects/README.md | 216 +++++++++--------- docs/book/src/troubleshooting/README.md | 14 +- 3 files changed, 227 insertions(+), 205 deletions(-) diff --git a/docs/book/src/editor_features/README.md b/docs/book/src/editor_features/README.md index 8ec05b9a3afb..833a1673cb76 100644 --- a/docs/book/src/editor_features/README.md +++ b/docs/book/src/editor_features/README.md @@ -8,22 +8,24 @@ It is possible to change the foreground/background color and font family/size of inlay hints. Just add this to your `settings.json`: - { - "editor.inlayHints.fontFamily": "Courier New", - "editor.inlayHints.fontSize": 11, - - "workbench.colorCustomizations": { - // Name of the theme you are currently using - "[Default Dark+]": { - "editorInlayHint.foreground": "#868686f0", - "editorInlayHint.background": "#3d3d3d48", - - // Overrides for specific kinds of inlay hints - "editorInlayHint.typeForeground": "#fdb6fdf0", - "editorInlayHint.parameterForeground": "#fdb6fdf0", - } - } +```json +{ + "editor.inlayHints.fontFamily": "Courier New", + "editor.inlayHints.fontSize": 11, + + "workbench.colorCustomizations": { + // Name of the theme you are currently using + "[Default Dark+]": { + "editorInlayHint.foreground": "#868686f0", + "editorInlayHint.background": "#3d3d3d48", + + // Overrides for specific kinds of inlay hints + "editorInlayHint.typeForeground": "#fdb6fdf0", + "editorInlayHint.parameterForeground": "#fdb6fdf0", + } } +} +``` ### Semantic style customizations @@ -32,46 +34,52 @@ code. For example, mutable bindings are underlined by default and you can override this behavior by adding the following section to your `settings.json`: - { - "editor.semanticTokenColorCustomizations": { - "rules": { - "*.mutable": { - "fontStyle": "", // underline is the default - }, - } - }, +```json +{ + "editor.semanticTokenColorCustomizations": { + "rules": { + "*.mutable": { + "fontStyle": "", // underline is the default + }, } + }, +} +``` Most themes doesnโ€™t support styling unsafe operations differently yet. You can fix this by adding overrides for the rules `operator.unsafe`, `function.unsafe`, and `method.unsafe`: - { - "editor.semanticTokenColorCustomizations": { - "rules": { - "operator.unsafe": "#ff6600", - "function.unsafe": "#ff6600", - "method.unsafe": "#ff6600" - } - }, - } +```json +{ + "editor.semanticTokenColorCustomizations": { + "rules": { + "operator.unsafe": "#ff6600", + "function.unsafe": "#ff6600", + "method.unsafe": "#ff6600" + } + }, +} +``` In addition to the top-level rules you can specify overrides for specific themes. For example, if you wanted to use a darker text color on a specific light theme, you might write: - { - "editor.semanticTokenColorCustomizations": { - "rules": { - "operator.unsafe": "#ff6600" - }, - "[Ayu Light]": { - "rules": { - "operator.unsafe": "#572300" - } - } - }, - } +```json +{ + "editor.semanticTokenColorCustomizations": { + "rules": { + "operator.unsafe": "#ff6600" + }, + "[Ayu Light]": { + "rules": { + "operator.unsafe": "#572300" + } + } + }, +} +``` Make sure you include the brackets around the theme name. For example, use `"[Ayu Light]"` to customize the theme Ayu Light. @@ -81,11 +89,13 @@ use `"[Ayu Light]"` to customize the theme Ayu Light. You may use `inRustProject` context to configure keybindings for rust projects only. For example: - { - "key": "ctrl+alt+d", - "command": "rust-analyzer.openDocs", - "when": "inRustProject" - } +```json +{ + "key": "ctrl+alt+d", + "command": "rust-analyzer.openDocs", + "when": "inRustProject" +} +``` More about `when` clause contexts [here](https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts). @@ -96,27 +106,31 @@ You can use "rust-analyzer.runnables.extraEnv" setting to define runnable environment-specific substitution variables. The simplest way for all runnables in a bunch: - "rust-analyzer.runnables.extraEnv": { - "RUN_SLOW_TESTS": "1" - } +```json +"rust-analyzer.runnables.extraEnv": { + "RUN_SLOW_TESTS": "1" +} +``` Or it is possible to specify vars more granularly: - "rust-analyzer.runnables.extraEnv": [ - { - // "mask": null, // null mask means that this rule will be applied for all runnables - env: { - "APP_ID": "1", - "APP_DATA": "asdf" - } - }, - { - "mask": "test_name", - "env": { - "APP_ID": "2", // overwrites only APP_ID - } +```json +"rust-analyzer.runnables.extraEnv": [ + { + // "mask": null, // null mask means that this rule will be applied for all runnables + env: { + "APP_ID": "1", + "APP_DATA": "asdf" + } + }, + { + "mask": "test_name", + "env": { + "APP_ID": "2", // overwrites only APP_ID } - ] + } +] +``` You can use any valid regular expression as a mask. Also note that a full runnable name is something like **run bin\_or\_example\_name**, @@ -127,25 +141,27 @@ this masks: `"^run"`, `"^test "` (the trailing space matters!), and If needed, you can set different values for different platforms: - "rust-analyzer.runnables.extraEnv": [ - { - "platform": "win32", // windows only - env: { - "APP_DATA": "windows specific data" - } - }, - { - "platform": ["linux"], - "env": { - "APP_DATA": "linux data", - } - }, - { // for all platforms - "env": { - "APP_COMMON_DATA": "xxx", - } +```json +"rust-analyzer.runnables.extraEnv": [ + { + "platform": "win32", // windows only + env: { + "APP_DATA": "windows specific data" + } + }, + { + "platform": ["linux"], + "env": { + "APP_DATA": "linux data", } - ] + }, + { // for all platforms + "env": { + "APP_COMMON_DATA": "xxx", + } + } +] +``` ### Compiler feedback from external commands @@ -161,14 +177,16 @@ For example, if you want to run [`cargo watch`](https://crates.io/crates/cargo-watch) instead, you might add the following to `.vscode/tasks.json`: - { - "label": "Watch", - "group": "build", - "type": "shell", - "command": "cargo watch", - "problemMatcher": "$rustc-watch", - "isBackground": true - } +```json +{ + "label": "Watch", + "group": "build", + "type": "shell", + "command": "cargo watch", + "problemMatcher": "$rustc-watch", + "isBackground": true +} +``` ### Live Share diff --git a/docs/book/src/non_cargo_based_projects/README.md b/docs/book/src/non_cargo_based_projects/README.md index bc286110a11c..4aa17883c65f 100644 --- a/docs/book/src/non_cargo_based_projects/README.md +++ b/docs/book/src/non_cargo_based_projects/README.md @@ -4,116 +4,118 @@ rust-analyzer does not require Cargo. However, if you use some other build system, youโ€™ll have to describe the structure of your project for rust-analyzer in the `rust-project.json` format: - interface JsonProject { - /// Path to the sysroot directory. - /// - /// The sysroot is where rustc looks for the - /// crates that are built-in to rust, such as - /// std. - /// - /// https://doc.rust-lang.org/rustc/command-line-arguments.html#--sysroot-override-the-system-root - /// - /// To see the current value of sysroot, you - /// can query rustc: - /// - /// ``` - /// $ rustc --print sysroot - /// /Users/yourname/.rustup/toolchains/stable-x86_64-apple-darwin - /// ``` - sysroot?: string; - /// Path to the directory with *source code* of - /// sysroot crates. - /// - /// By default, this is `lib/rustlib/src/rust/library` - /// relative to the sysroot. - /// - /// It should point to the directory where std, - /// core, and friends can be found: - /// - /// https://github.com/rust-lang/rust/tree/master/library. - /// - /// If provided, rust-analyzer automatically adds - /// dependencies on sysroot crates. Conversely, - /// if you omit this path, you can specify sysroot - /// dependencies yourself and, for example, have - /// several different "sysroots" in one graph of - /// crates. - sysroot_src?: string; - /// The set of crates comprising the current - /// project. Must include all transitive - /// dependencies as well as sysroot crate (libstd, - /// libcore and such). - crates: Crate[]; - } +```typescript +interface JsonProject { + /// Path to the sysroot directory. + /// + /// The sysroot is where rustc looks for the + /// crates that are built-in to rust, such as + /// std. + /// + /// https://doc.rust-lang.org/rustc/command-line-arguments.html#--sysroot-override-the-system-root + /// + /// To see the current value of sysroot, you + /// can query rustc: + /// + /// ``` + /// $ rustc --print sysroot + /// /Users/yourname/.rustup/toolchains/stable-x86_64-apple-darwin + /// ``` + sysroot?: string; + /// Path to the directory with *source code* of + /// sysroot crates. + /// + /// By default, this is `lib/rustlib/src/rust/library` + /// relative to the sysroot. + /// + /// It should point to the directory where std, + /// core, and friends can be found: + /// + /// https://github.com/rust-lang/rust/tree/master/library. + /// + /// If provided, rust-analyzer automatically adds + /// dependencies on sysroot crates. Conversely, + /// if you omit this path, you can specify sysroot + /// dependencies yourself and, for example, have + /// several different "sysroots" in one graph of + /// crates. + sysroot_src?: string; + /// The set of crates comprising the current + /// project. Must include all transitive + /// dependencies as well as sysroot crate (libstd, + /// libcore and such). + crates: Crate[]; +} - interface Crate { - /// Optional crate name used for display purposes, - /// without affecting semantics. See the `deps` - /// key for semantically-significant crate names. - display_name?: string; - /// Path to the root module of the crate. - root_module: string; - /// Edition of the crate. - edition: "2015" | "2018" | "2021"; - /// Dependencies - deps: Dep[]; - /// Should this crate be treated as a member of - /// current "workspace". - /// - /// By default, inferred from the `root_module` - /// (members are the crates which reside inside - /// the directory opened in the editor). - /// - /// Set this to `false` for things like standard - /// library and 3rd party crates to enable - /// performance optimizations (rust-analyzer - /// assumes that non-member crates don't change). - is_workspace_member?: boolean; - /// Optionally specify the (super)set of `.rs` - /// files comprising this crate. - /// - /// By default, rust-analyzer assumes that only - /// files under `root_module.parent` can belong - /// to a crate. `include_dirs` are included - /// recursively, unless a subdirectory is in - /// `exclude_dirs`. - /// - /// Different crates can share the same `source`. - /// - /// If two crates share an `.rs` file in common, - /// they *must* have the same `source`. - /// rust-analyzer assumes that files from one - /// source can't refer to files in another source. - source?: { - include_dirs: string[], - exclude_dirs: string[], - }, - /// The set of cfgs activated for a given crate, like - /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`. - cfg: string[]; - /// Target triple for this Crate. - /// - /// Used when running `rustc --print cfg` - /// to get target-specific cfgs. - target?: string; - /// Environment variables, used for - /// the `env!` macro - env: { [key: string]: string; }, +interface Crate { + /// Optional crate name used for display purposes, + /// without affecting semantics. See the `deps` + /// key for semantically-significant crate names. + display_name?: string; + /// Path to the root module of the crate. + root_module: string; + /// Edition of the crate. + edition: "2015" | "2018" | "2021"; + /// Dependencies + deps: Dep[]; + /// Should this crate be treated as a member of + /// current "workspace". + /// + /// By default, inferred from the `root_module` + /// (members are the crates which reside inside + /// the directory opened in the editor). + /// + /// Set this to `false` for things like standard + /// library and 3rd party crates to enable + /// performance optimizations (rust-analyzer + /// assumes that non-member crates don't change). + is_workspace_member?: boolean; + /// Optionally specify the (super)set of `.rs` + /// files comprising this crate. + /// + /// By default, rust-analyzer assumes that only + /// files under `root_module.parent` can belong + /// to a crate. `include_dirs` are included + /// recursively, unless a subdirectory is in + /// `exclude_dirs`. + /// + /// Different crates can share the same `source`. + /// + /// If two crates share an `.rs` file in common, + /// they *must* have the same `source`. + /// rust-analyzer assumes that files from one + /// source can't refer to files in another source. + source?: { + include_dirs: string[], + exclude_dirs: string[], + }, + /// The set of cfgs activated for a given crate, like + /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`. + cfg: string[]; + /// Target triple for this Crate. + /// + /// Used when running `rustc --print cfg` + /// to get target-specific cfgs. + target?: string; + /// Environment variables, used for + /// the `env!` macro + env: { [key: string]: string; }, - /// Whether the crate is a proc-macro crate. - is_proc_macro: boolean; - /// For proc-macro crates, path to compiled - /// proc-macro (.so file). - proc_macro_dylib_path?: string; - } + /// Whether the crate is a proc-macro crate. + is_proc_macro: boolean; + /// For proc-macro crates, path to compiled + /// proc-macro (.so file). + proc_macro_dylib_path?: string; +} - interface Dep { - /// Index of a crate in the `crates` array. - crate: number, - /// Name as should appear in the (implicit) - /// `extern crate name` declaration. - name: string, - } +interface Dep { + /// Index of a crate in the `crates` array. + crate: number, + /// Name as should appear in the (implicit) + /// `extern crate name` declaration. + name: string, +} +``` This format is provisional and subject to change. Specifically, the `roots` setup will be different eventually. diff --git a/docs/book/src/troubleshooting/README.md b/docs/book/src/troubleshooting/README.md index 02d0affe6f0b..dd41a6227843 100644 --- a/docs/book/src/troubleshooting/README.md +++ b/docs/book/src/troubleshooting/README.md @@ -34,15 +34,17 @@ bypassing LSP machinery. When filing issues, it is useful (but not necessary) to try to minimize examples. An ideal bug reproduction looks like this: - $ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash - $ rust-analyzer --version - rust-analyzer dd12184e4 2021-05-08 dev - $ rust-analyzer analysis-stats . - ๐Ÿ’€ ๐Ÿ’€ ๐Ÿ’€ +```shell +$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash +$ rust-analyzer --version +rust-analyzer dd12184e4 2021-05-08 dev +$ rust-analyzer analysis-stats . +๐Ÿ’€ ๐Ÿ’€ ๐Ÿ’€ +``` It is especially useful when the `repo` doesnโ€™t use external crates or the standard library. If you want to go as far as to modify the source code to debug the problem, be sure to take a look at the [dev -docs](https://github.com/rust-lang/rust-analyzer/tree/master/docs/dev)! \ No newline at end of file +docs](https://github.com/rust-lang/rust-analyzer/tree/master/docs/dev)!