Skip to content

Commit deda58e

Browse files
WilfredVeykriljoshrotenberg
committed
manual: Convert to mdbook
Split manual.adoc into markdown files, one for each chapter. For the parts of the manual that are generated from source code doc comments, update the comments to use markdown syntax and update the code generators to write to `generated.md` files. For the weekly release, stop copying the .adoc files to the `rust-analyzer/rust-analyzer.github.io` at release time. Instead, we'll sync the manual hourly from this repository. See rust-analyzer/rust-analyzer.github.io#226 for the sync. This PR should be merged first, and that PR needs to be merged before the next weekly release. This change is based on #15795, but rebased and updated. I've also manually checked each page for markdown syntax issues and fixed any I encountered. Co-authored-by: Lukas Wirth <lukastw97@gmail.com> Co-authored-by: Josh Rotenberg <joshrotenberg@gmail.com>
1 parent 6e4c29f commit deda58e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+2836
-2686
lines changed

‎.gitignore

+4-3
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@ target/
66
*.log
77
*.iml
88
.vscode/settings.json
9-
generated_assists.adoc
10-
generated_features.adoc
11-
generated_diagnostic.adoc
129
.DS_Store
1310
/out/
1411
/dump.lsif
1512
.envrc
13+
docs/book/book
14+
docs/book/src/assists_generated.md
15+
docs/book/src/diagnostics_generated.md
16+
docs/book/src/features_generated.md

‎crates/ide-assists/src/handlers/apply_demorgan.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ use crate::{utils::invert_boolean_expression, AssistContext, AssistId, AssistKin
1515

1616
// Assist: apply_demorgan
1717
//
18-
// Apply https://en.wikipedia.org/wiki/De_Morgan%27s_laws[De Morgan's law].
18+
// Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
1919
// This transforms expressions of the form `!l || !r` into `!(l && r)`.
2020
// This also works with `&&`. This assist can only be applied with the cursor
2121
// on either `||` or `&&`.
@@ -131,7 +131,7 @@ pub(crate) fn apply_demorgan(acc: &mut Assists, ctx: &AssistContext<'_>) -> Opti
131131

132132
// Assist: apply_demorgan_iterator
133133
//
134-
// Apply https://en.wikipedia.org/wiki/De_Morgan%27s_laws[De Morgan's law] to
134+
// Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws) to
135135
// `Iterator::all` and `Iterator::any`.
136136
//
137137
// This transforms expressions of the form `!iter.any(|x| predicate(x))` into

‎crates/ide-assists/src/handlers/auto_import.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
3838
// use super::AssistContext;
3939
// ```
4040
//
41-
// .Import Granularity
41+
// #### Import Granularity
4242
//
4343
// It is possible to configure how use-trees are merged with the `imports.granularity.group` setting.
4444
// It has the following configurations:
@@ -54,7 +54,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
5454
//
5555
// In `VS Code` the configuration for this is `rust-analyzer.imports.granularity.group`.
5656
//
57-
// .Import Prefix
57+
// #### Import Prefix
5858
//
5959
// The style of imports in the same crate is configurable through the `imports.prefix` setting.
6060
// It has the following configurations:
@@ -68,7 +68,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
6868
//
6969
// In `VS Code` the configuration for this is `rust-analyzer.imports.prefix`.
7070
//
71-
// image::https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif[]
71+
// ![Auto Import](https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif)
7272

7373
// Assist: auto_import
7474
//

‎crates/ide-assists/src/tests/generated.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! Generated by `cargo codegen assists-doc-tests`, do not edit by hand.
1+
//! Generated by `cargo xtask codegen assists-doc-tests`, do not edit by hand.
22
33
use super::check_doc_test;
44

‎crates/ide-completion/src/completions/flyimport.rs

+4-4
Original file line numberDiff line numberDiff line change
@@ -83,27 +83,27 @@ use crate::{
8383
// NOTE: currently, if an assoc item comes from a trait that's not currently imported, and it also has an unresolved and/or partially-qualified path,
8484
// no imports will be proposed.
8585
//
86-
// .Fuzzy search details
86+
// #### Fuzzy search details
8787
//
8888
// To avoid an excessive amount of the results returned, completion input is checked for inclusion in the names only
8989
// (i.e. in `HashMap` in the `std::collections::HashMap` path).
9090
// For the same reasons, avoids searching for any path imports for inputs with their length less than 2 symbols
9191
// (but shows all associated items for any input length).
9292
//
93-
// .Import configuration
93+
// #### Import configuration
9494
//
9595
// It is possible to configure how use-trees are merged with the `imports.granularity.group` setting.
9696
// Mimics the corresponding behavior of the `Auto Import` feature.
9797
//
98-
// .LSP and performance implications
98+
// #### LSP and performance implications
9999
//
100100
// The feature is enabled only if the LSP client supports LSP protocol version 3.16+ and reports the `additionalTextEdits`
101101
// (case-sensitive) resolve client capability in its client capabilities.
102102
// This way the server is able to defer the costly computations, doing them for a selected completion item only.
103103
// For clients with no such support, all edits have to be calculated on the completion request, including the fuzzy search completion ones,
104104
// which might be slow ergo the feature is automatically disabled.
105105
//
106-
// .Feature toggle
106+
// #### Feature toggle
107107
//
108108
// The feature can be forcefully turned off in the settings with the `rust-analyzer.completion.autoimport.enable` flag.
109109
// Note that having this flag set to `true` does not guarantee that the feature is enabled: your client needs to have the corresponding

‎crates/ide-completion/src/completions/postfix/format_like.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
// ** `logw` -> `log::warn!(...)`
1515
// ** `loge` -> `log::error!(...)`
1616
//
17-
// image::https://user-images.githubusercontent.com/48062697/113020656-b560f500-917a-11eb-87de-02991f61beb8.gif[]
17+
// ![Format String Completion](https://user-images.githubusercontent.com/48062697/113020656-b560f500-917a-11eb-87de-02991f61beb8.gif)
1818

1919
use ide_db::{
2020
syntax_helpers::format_string_exprs::{parse_format_exprs, with_placeholders, Arg},

‎crates/ide-completion/src/lib.rs

+5-3
Original file line numberDiff line numberDiff line change
@@ -110,11 +110,13 @@ impl CompletionFieldsToResolve {
110110
//
111111
// There also snippet completions:
112112
//
113-
// .Expressions
113+
// #### Expressions
114+
//
114115
// - `pd` -> `eprintln!(" = {:?}", );`
115116
// - `ppd` -> `eprintln!(" = {:#?}", );`
116117
//
117-
// .Items
118+
// #### Items
119+
//
118120
// - `tfn` -> `#[test] fn feature(){}`
119121
// - `tmod` ->
120122
// ```rust
@@ -131,7 +133,7 @@ impl CompletionFieldsToResolve {
131133
// Those are the additional completion options with automatic `use` import and options from all project importable items,
132134
// fuzzy matched against the completion input.
133135
//
134-
// image::https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif[]
136+
// ![Magic Completions](https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif)
135137

136138
/// Main entry point for completion. We run completion as a two-phase process.
137139
///

‎crates/ide-completion/src/snippet.rs

+6-6
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@
88
//
99
// A custom snippet can be defined by adding it to the `rust-analyzer.completion.snippets.custom` object respectively.
1010
//
11-
// [source,json]
12-
// ----
11+
// ```json
1312
// {
1413
// "rust-analyzer.completion.snippets.custom": {
1514
// "thread spawn": {
@@ -25,7 +24,7 @@
2524
// }
2625
// }
2726
// }
28-
// ----
27+
// ```
2928
//
3029
// In the example above:
3130
//
@@ -39,6 +38,7 @@
3938
// * `description` is an optional description of the snippet, if unset the snippet name will be used.
4039
//
4140
// * `requires` is an optional list of item paths that have to be resolvable in the current crate where the completion is rendered.
41+
4242
// On failure of resolution the snippet won't be applicable, otherwise the snippet will insert an import for the items on insertion if
4343
// the items aren't yet in scope.
4444
//
@@ -55,8 +55,8 @@
5555
//
5656
// For the VSCode editor, rust-analyzer also ships with a small set of defaults which can be removed
5757
// by overwriting the settings object mentioned above, the defaults are:
58-
// [source,json]
59-
// ----
58+
//
59+
// ```json
6060
// {
6161
// "Arc::new": {
6262
// "postfix": "arc",
@@ -98,7 +98,7 @@
9898
// "scope": "expr"
9999
// }
100100
// }
101-
// ----
101+
// ````
102102

103103
use hir::{ModPath, Name, Symbol};
104104
use ide_db::imports::import_assets::LocatedImport;

‎crates/ide-db/src/apply_change.rs

+4-5
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,11 @@ impl RootDatabase {
4444
//
4545
// Clears rust-analyzer's internal database and prints memory usage statistics.
4646
//
47-
// |===
48-
// | Editor | Action Name
49-
//
47+
// | Editor | Action Name |
48+
// |---------|-------------|
5049
// | VS Code | **rust-analyzer: Memory Usage (Clears Database)**
51-
// |===
52-
// image::https://user-images.githubusercontent.com/48062697/113065592-08559f00-91b1-11eb-8c96-64b88068ec02.gif[]
50+
51+
// ![Memory Usage](https://user-images.githubusercontent.com/48062697/113065592-08559f00-91b1-11eb-8c96-64b88068ec02.gif)
5352
pub fn per_query_memory_usage(&mut self) -> Vec<(String, Bytes, usize)> {
5453
let mut acc: Vec<(String, Bytes, usize)> = vec![];
5554

‎crates/ide-db/src/symbol_index.rs

+3-5
Original file line numberDiff line numberDiff line change
@@ -193,11 +193,9 @@ impl<DB> std::ops::Deref for Snap<DB> {
193193
// `rust-analyzer.workspace.symbol.search.kind` settings. Symbols prefixed
194194
// with `__` are hidden from the search results unless configured otherwise.
195195
//
196-
// |===
197-
// | Editor | Shortcut
198-
//
199-
// | VS Code | kbd:[Ctrl+T]
200-
// |===
196+
// | Editor | Shortcut |
197+
// |---------|-----------|
198+
// | VS Code | <kbd>Ctrl+T</kbd>
201199
pub fn world_symbols(db: &RootDatabase, query: Query) -> Vec<FileSymbol> {
202200
let _p = tracing::info_span!("world_symbols", query = ?query.query).entered();
203201

‎crates/ide-diagnostics/src/handlers/incorrect_case.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ use crate::{
1212

1313
// Diagnostic: incorrect-ident-case
1414
//
15-
// This diagnostic is triggered if an item name doesn't follow https://doc.rust-lang.org/1.0.0/style/style/naming/README.html[Rust naming convention].
15+
// This diagnostic is triggered if an item name doesn't follow [Rust naming convention](https://doc.rust-lang.org/1.0.0/style/style/naming/README.html).
1616
pub(crate) fn incorrect_case(ctx: &DiagnosticsContext<'_>, d: &hir::IncorrectCase) -> Diagnostic {
1717
let code = match d.expected_case {
1818
CaseType::LowerSnakeCase => DiagnosticCode::RustcLint("non_snake_case"),

‎crates/ide-ssr/src/lib.rs

+7-11
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,10 @@
3333
//
3434
// Supported constraints:
3535
//
36-
// |===
37-
// | Constraint | Restricts placeholder
38-
//
39-
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`)
40-
// | not(a) | Negates the constraint `a`
41-
// |===
36+
// | Constraint | Restricts placeholder |
37+
// |---------------|------------------------|
38+
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`) |
39+
// | not(a) | Negates the constraint `a` |
4240
//
4341
// Available via the command `rust-analyzer.ssr`.
4442
//
@@ -52,11 +50,9 @@
5250
// String::from((y + 5).foo(z))
5351
// ```
5452
//
55-
// |===
56-
// | Editor | Action Name
57-
//
58-
// | VS Code | **rust-analyzer: Structural Search Replace**
59-
// |===
53+
// | Editor | Action Name |
54+
// |---------|--------------|
55+
// | VS Code | **rust-analyzer: Structural Search Replace** |
6056
//
6157
// Also available as an assist, by writing a comment containing the structural
6258
// search and replace rule. You will only see the assist if the comment can

‎crates/ide/src/annotations.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ mod fn_references;
2121
// Provides user with annotations above items for looking up references or impl blocks
2222
// and running/debugging binaries.
2323
//
24-
// image::https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png[]
24+
// ![Annotations](https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png)
2525
#[derive(Debug, Hash, PartialEq, Eq)]
2626
pub struct Annotation {
2727
pub range: TextRange,

‎crates/ide/src/doc_links.rs

+3-5
Original file line numberDiff line numberDiff line change
@@ -122,11 +122,9 @@ pub(crate) fn remove_links(markdown: &str) -> String {
122122
// The simplest way to use this feature is via the context menu. Right-click on
123123
// the selected item. The context menu opens. Select **Open Docs**.
124124
//
125-
// |===
126-
// | Editor | Action Name
127-
//
128-
// | VS Code | **rust-analyzer: Open Docs**
129-
// |===
125+
// | Editor | Action Name |
126+
// |---------|-------------|
127+
// | VS Code | **rust-analyzer: Open Docs** |
130128
pub(crate) fn external_docs(
131129
db: &RootDatabase,
132130
FilePosition { file_id, offset }: FilePosition,

‎crates/ide/src/expand_macro.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,11 @@ pub struct ExpandedMacro {
1919
//
2020
// Shows the full macro expansion of the macro at the current caret position.
2121
//
22-
// |===
23-
// | Editor | Action Name
22+
// | Editor | Action Name |
23+
// |---------|-------------|
24+
// | VS Code | **rust-analyzer: Expand macro recursively at caret** |
2425
//
25-
// | VS Code | **rust-analyzer: Expand macro recursively at caret**
26-
// |===
27-
//
28-
// image::https://user-images.githubusercontent.com/48062697/113020648-b3973180-917a-11eb-84a9-ecb921293dc5.gif[]
26+
// ![Expand Macro Recursively](https://user-images.githubusercontent.com/48062697/113020648-b3973180-917a-11eb-84a9-ecb921293dc5.gif)
2927
pub(crate) fn expand_macro(db: &RootDatabase, position: FilePosition) -> Option<ExpandedMacro> {
3028
let sema = Semantics::new(db);
3129
let file = sema.parse_guess_edition(position.file_id);

‎crates/ide/src/extend_selection.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,11 @@ use crate::FileRange;
1717
// Extends or shrinks the current selection to the encompassing syntactic construct
1818
// (expression, statement, item, module, etc). It works with multiple cursors.
1919
//
20-
// |===
21-
// | Editor | Shortcut
20+
// | Editor | Shortcut |
21+
// |---------|----------|
22+
// | VS Code | <kbd>Alt+Shift+→</kbd>, <kbd>Alt+Shift+←</kbd> |
2223
//
23-
// | VS Code | kbd:[Alt+Shift+→], kbd:[Alt+Shift+←]
24-
// |===
25-
//
26-
// image::https://user-images.githubusercontent.com/48062697/113020651-b42fc800-917a-11eb-8a4f-cf1a07859fac.gif[]
24+
// ![Expand and Shrink Selection](https://user-images.githubusercontent.com/48062697/113020651-b42fc800-917a-11eb-8a4f-cf1a07859fac.gif)
2725
pub(crate) fn extend_selection(db: &RootDatabase, frange: FileRange) -> TextRange {
2826
let sema = Semantics::new(db);
2927
let src = sema.parse_guess_edition(frange.file_id);

‎crates/ide/src/fetch_crates.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,11 @@ pub struct CrateInfo {
1414
//
1515
// Shows a view tree with all the dependencies of this project
1616
//
17-
// |===
18-
// | Editor | Panel Name
17+
// | Editor | Panel Name |
18+
// |---------|------------|
19+
// | VS Code | **Rust Dependencies** |
1920
//
20-
// | VS Code | **Rust Dependencies**
21-
// |===
22-
//
23-
// image::https://user-images.githubusercontent.com/5748995/229394139-2625beab-f4c9-484b-84ed-ad5dee0b1e1a.png[]
21+
// ![Show Dependency Tree](https://user-images.githubusercontent.com/5748995/229394139-2625beab-f4c9-484b-84ed-ad5dee0b1e1a.png)
2422
pub(crate) fn fetch_crates(db: &RootDatabase) -> FxIndexSet<CrateInfo> {
2523
let crate_graph = db.crate_graph();
2624
crate_graph

‎crates/ide/src/file_structure.rs

+4-7
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,11 @@ pub enum StructureNodeKind {
3131
// * draw breadcrumbs to describe the context around the cursor
3232
// * draw outline of the file
3333
//
34-
// |===
35-
// | Editor | Shortcut
34+
// | Editor | Shortcut |
35+
// |---------|----------|
36+
// | VS Code | <kbd>Ctrl+Shift+O</kbd> |
3637
//
37-
// | VS Code | kbd:[Ctrl+Shift+O]
38-
// |===
39-
//
40-
// image::https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif[]
41-
38+
// ![File Structure](https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif)
4239
pub(crate) fn file_structure(file: &SourceFile) -> Vec<StructureNode> {
4340
let mut res = Vec::new();
4441
let mut stack = Vec::new();

‎crates/ide/src/goto_definition.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,11 @@ use syntax::{
3131
//
3232
// For outline modules, this will navigate to the source file of the module.
3333
//
34-
// |===
35-
// | Editor | Shortcut
34+
// | Editor | Shortcut |
35+
// |---------|----------|
36+
// | VS Code | <kbd>F12</kbd> |
3637
//
37-
// | VS Code | kbd:[F12]
38-
// |===
39-
//
40-
// image::https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif[]
38+
// ![Go to Definition](https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif)
4139
pub(crate) fn goto_definition(
4240
db: &RootDatabase,
4341
FilePosition { file_id, offset }: FilePosition,

‎crates/ide/src/goto_implementation.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,11 @@ use crate::{FilePosition, NavigationTarget, RangeInfo, TryToNav};
1212
//
1313
// Navigates to the impl items of types.
1414
//
15-
// |===
16-
// | Editor | Shortcut
15+
// | Editor | Shortcut |
16+
// |---------|----------|
17+
// | VS Code | <kbd>Ctrl+F12</kbd>
1718
//
18-
// | VS Code | kbd:[Ctrl+F12]
19-
// |===
20-
//
21-
// image::https://user-images.githubusercontent.com/48062697/113065566-02f85480-91b1-11eb-9288-aaad8abd8841.gif[]
19+
// ![Go to Implementation](https://user-images.githubusercontent.com/48062697/113065566-02f85480-91b1-11eb-9288-aaad8abd8841.gif)
2220
pub(crate) fn goto_implementation(
2321
db: &RootDatabase,
2422
FilePosition { file_id, offset }: FilePosition,

0 commit comments

Comments
 (0)