Skip to content

Commit 54f8c7e

Browse files
joshrotenbergjoshrotenberg
committed
convert manual to mdbook
manual.adoc to markdown add entire static manual and toc move generated adoc to md in book dir add features add features add assists add config add diagnostics split up book, clean up links update book config add intro remove old docs, add a README clean up ignores add temporary workflow temporary makefile remove workflow Fix import preference config keys convert manual to mdbook manual.adoc to markdown add entire static manual and toc move generated adoc to md in book dir add features add features add assists add config add diagnostics split up book, clean up links update book config add intro remove old docs, add a README clean up ignores add temporary workflow temporary makefile remove workflow remove generated config.md rework generated locations and ignores remove img, replace with externally linked remove img, replace with externally linked these should be gone
1 parent 416e9c8 commit 54f8c7e

Some content is hidden

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

68 files changed

+7136
-2235
lines changed

‎.gitignore

+2-3
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,9 @@ crates/*/target
77
*.log
88
*.iml
99
.vscode/settings.json
10-
generated_assists.adoc
11-
generated_features.adoc
12-
generated_diagnostic.adoc
1310
.DS_Store
1411
/out/
1512
/dump.lsif
1613
.envrc
14+
docs/book/book
15+
docs/book/src/*/generated.md

‎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:
@@ -52,7 +52,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
5252
//
5353
// In `VS Code` the configuration for this is `rust-analyzer.imports.granularity.group`.
5454
//
55-
// .Import Prefix
55+
// #### Import Prefix
5656
//
5757
// The style of imports in the same crate is configurable through the `imports.prefix` setting.
5858
// It has the following configurations:
@@ -66,7 +66,7 @@ use crate::{AssistContext, AssistId, AssistKind, Assists, GroupLabel};
6666
//
6767
// In `VS Code` the configuration for this is `rust-analyzer.imports.prefix`.
6868
//
69-
// image::https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif[]
69+
// ![Auto Import](https://user-images.githubusercontent.com/48062697/113020673-b85be580-917a-11eb-9022-59585f35d4f8.gif)
7070

7171
// Assist: auto_import
7272
//

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ r#####"
5555
"sourcegen_assists_docs",
5656
assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n"),
5757
);
58-
let dst = project_root().join("docs/user/generated_assists.adoc");
58+
let dst = project_root().join("docs/book/src/assists/generated.md");
5959
fs::write(dst, contents).unwrap();
6060
}
6161
}
@@ -139,7 +139,7 @@ impl fmt::Display for Assist {
139139
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
140140
let _ = writeln!(
141141
f,
142-
"[discrete]\n=== `{}`
142+
"### `{}`
143143
**Source:** {}",
144144
self.id, self.location,
145145
);
@@ -152,11 +152,11 @@ impl fmt::Display for Assist {
152152
"
153153
{}
154154
155-
.Before
155+
#### Before
156156
```rust
157157
{}```
158158
159-
.After
159+
#### After
160160
```rust
161161
{}```",
162162
section.doc,

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -82,27 +82,27 @@ use crate::{
8282
// 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,
8383
// no imports will be proposed.
8484
//
85-
// .Fuzzy search details
85+
// #### Fuzzy search details
8686
//
8787
// To avoid an excessive amount of the results returned, completion input is checked for inclusion in the names only
8888
// (i.e. in `HashMap` in the `std::collections::HashMap` path).
8989
// For the same reasons, avoids searching for any path imports for inputs with their length less than 2 symbols
9090
// (but shows all associated items for any input length).
9191
//
92-
// .Import configuration
92+
// #### Import configuration
9393
//
9494
// It is possible to configure how use-trees are merged with the `imports.granularity.group` setting.
9595
// Mimics the corresponding behavior of the `Auto Import` feature.
9696
//
97-
// .LSP and performance implications
97+
// #### LSP and performance implications
9898
//
9999
// The feature is enabled only if the LSP client supports LSP protocol version 3.16+ and reports the `additionalTextEdits`
100100
// (case-sensitive) resolve client capability in its client capabilities.
101101
// This way the server is able to defer the costly computations, doing them for a selected completion item only.
102102
// For clients with no such support, all edits have to be calculated on the completion request, including the fuzzy search completion ones,
103103
// which might be slow ergo the feature is automatically disabled.
104104
//
105-
// .Feature toggle
105+
// #### Feature toggle
106106
//
107107
// The feature can be forcefully turned off in the settings with the `rust-analyzer.completion.autoimport.enable` flag.
108108
// 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},

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

+5-3
Original file line numberDiff line numberDiff line change
@@ -72,11 +72,13 @@ pub use crate::{
7272
//
7373
// There also snippet completions:
7474
//
75-
// .Expressions
75+
// #### Expressions
76+
//
7677
// - `pd` -> `eprintln!(" = {:?}", );`
7778
// - `ppd` -> `eprintln!(" = {:#?}", );`
7879
//
79-
// .Items
80+
// #### Items
81+
//
8082
// - `tfn` -> `#[test] fn feature(){}`
8183
// - `tmod` ->
8284
// ```rust
@@ -93,7 +95,7 @@ pub use crate::{
9395
// Those are the additional completion options with automatic `use` import and options from all project importable items,
9496
// fuzzy matched against the completion input.
9597
//
96-
// image::https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif[]
98+
// ![Magic Completions](https://user-images.githubusercontent.com/48062697/113020667-b72ab880-917a-11eb-8778-716cf26a0eb3.gif)
9799

98100
/// Main entry point for completion. We run completion as a two-phase process.
99101
///

‎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 ide_db::imports::import_assets::LocatedImport;
104104
use itertools::Itertools;

‎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
@@ -199,11 +199,9 @@ impl<DB> std::ops::Deref for Snap<DB> {
199199
// the filtering via the `rust-analyzer.workspace.symbol.search.scope` and
200200
// `rust-analyzer.workspace.symbol.search.kind` settings.
201201
//
202-
// |===
203-
// | Editor | Shortcut
204-
//
205-
// | VS Code | kbd:[Ctrl+T]
206-
// |===
202+
// | Editor | Shortcut |
203+
// |---------|-----------|
204+
// | VS Code | <kbd>Ctrl+T</kbd>
207205
pub fn world_symbols(db: &RootDatabase, query: Query) -> Vec<FileSymbol> {
208206
let _p = profile::span("world_symbols").detail(|| query.query.clone());
209207

‎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-diagnostics/src/tests/sourcegen.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ fn sourcegen_diagnostic_docs() {
1010
let contents =
1111
diagnostics.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
1212
let contents = sourcegen::add_preamble("sourcegen_diagnostic_docs", contents);
13-
let dst = project_root().join("docs/user/generated_diagnostic.adoc");
13+
let dst = project_root().join("docs/book/src/diagnostics/generated.md");
1414
fs::write(dst, contents).unwrap();
1515
}
1616

@@ -68,6 +68,6 @@ fn is_valid_diagnostic_name(diagnostic: &str) -> Result<(), String> {
6868

6969
impl fmt::Display for Diagnostic {
7070
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71-
writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
71+
writeln!(f, "#### {}\n\nSource: {}\n\n{}\n\n", self.id, self.location, self.doc)
7272
}
7373
}

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

+7-11
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,10 @@
3535
//
3636
// Supported constraints:
3737
//
38-
// |===
39-
// | Constraint | Restricts placeholder
40-
//
41-
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`)
42-
// | not(a) | Negates the constraint `a`
43-
// |===
38+
// | Constraint | Restricts placeholder |
39+
// |---------------|------------------------|
40+
// | kind(literal) | Is a literal (e.g. `42` or `"forty two"`) |
41+
// | not(a) | Negates the constraint `a` |
4442
//
4543
// Available via the command `rust-analyzer.ssr`.
4644
//
@@ -54,11 +52,9 @@
5452
// String::from((y + 5).foo(z))
5553
// ```
5654
//
57-
// |===
58-
// | Editor | Action Name
59-
//
60-
// | VS Code | **rust-analyzer: Structural Search Replace**
61-
// |===
55+
// | Editor | Action Name |
56+
// |---------|--------------|
57+
// | VS Code | **rust-analyzer: Structural Search Replace** |
6258
//
6359
// Also available as an assist, by writing a comment containing the structural
6460
// 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
@@ -22,7 +22,7 @@ mod fn_references;
2222
// Provides user with annotations above items for looking up references or impl blocks
2323
// and running/debugging binaries.
2424
//
25-
// image::https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png[]
25+
// ![Annotations](https://user-images.githubusercontent.com/48062697/113020672-b7c34f00-917a-11eb-8f6e-858735660a0e.png)
2626
#[derive(Debug)]
2727
pub struct Annotation {
2828
pub range: TextRange,

‎crates/ide/src/doc_links.rs

+3-5
Original file line numberDiff line numberDiff line change
@@ -125,11 +125,9 @@ pub(crate) fn remove_links(markdown: &str) -> String {
125125
// The simplest way to use this feature is via the context menu. Right-click on
126126
// the selected item. The context menu opens. Select **Open Docs**.
127127
//
128-
// |===
129-
// | Editor | Action Name
130-
//
131-
// | VS Code | **rust-analyzer: Open Docs**
132-
// |===
128+
// | Editor | Action Name |
129+
// |---------|-------------|
130+
// | VS Code | **rust-analyzer: Open Docs** |
133131
pub(crate) fn external_docs(
134132
db: &RootDatabase,
135133
FilePosition { file_id, offset }: FilePosition,

‎crates/ide/src/expand_macro.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,11 @@ pub struct ExpandedMacro {
1616
//
1717
// Shows the full macro expansion of the macro at the current caret position.
1818
//
19-
// |===
20-
// | Editor | Action Name
19+
// | Editor | Action Name |
20+
// |---------|-------------|
21+
// | VS Code | **rust-analyzer: Expand macro recursively** |
2122
//
22-
// | VS Code | **rust-analyzer: Expand macro recursively at caret**
23-
// |===
24-
//
25-
// image::https://user-images.githubusercontent.com/48062697/113020648-b3973180-917a-11eb-84a9-ecb921293dc5.gif[]
23+
// ![Expand Macro Recursively](/img/features/expand_macro_recursively.gif)
2624
pub(crate) fn expand_macro(db: &RootDatabase, position: FilePosition) -> Option<ExpandedMacro> {
2725
let sema = Semantics::new(db);
2826
let file = sema.parse(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(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
@@ -30,14 +30,11 @@ pub enum StructureNodeKind {
3030
// * draw breadcrumbs to describe the context around the cursor
3131
// * draw outline of the file
3232
//
33-
// |===
34-
// | Editor | Shortcut
33+
// | Editor | Shortcut |
34+
// |---------|----------|
35+
// | VS Code | <kbd>Ctrl+Shift+O</kbd> |
3536
//
36-
// | VS Code | kbd:[Ctrl+Shift+O]
37-
// |===
38-
//
39-
// image::https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif[]
40-
37+
// ![File Structure](https://user-images.githubusercontent.com/48062697/113020654-b42fc800-917a-11eb-8388-e7dc4d92b02e.gif)
4138
pub(crate) fn file_structure(file: &SourceFile) -> Vec<StructureNode> {
4239
let mut res = Vec::new();
4340
let mut stack = Vec::new();

‎crates/ide/src/goto_definition.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,11 @@ use syntax::{ast, AstNode, AstToken, SyntaxKind::*, SyntaxToken, TextRange, T};
2020
//
2121
// For outline modules, this will navigate to the source file of the module.
2222
//
23-
// |===
24-
// | Editor | Shortcut
23+
// | Editor | Shortcut |
24+
// |---------|----------|
25+
// | VS Code | <kbd>F12</kbd> |
2526
//
26-
// | VS Code | kbd:[F12]
27-
// |===
28-
//
29-
// image::https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif[]
27+
// ![Go to Definition](https://user-images.githubusercontent.com/48062697/113065563-025fbe00-91b1-11eb-83e4-a5a703610b23.gif)
3028
pub(crate) fn goto_definition(
3129
db: &RootDatabase,
3230
FilePosition { file_id, offset }: FilePosition,

0 commit comments

Comments
 (0)