tonywu.org / mdbookkit
toolkit for mdBook [mirror of my GitHub repo] docs.tonywu.dev/mdbookkit/
permalinks rust-analyzer mdbook
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

[docs] finalize book

Tony Wu 67d3d9e5 4fdef6c9

+321 -257
+3 -4
crates/mdbookkit/README.md
··· 1 1 # mdbookkit 2 2 3 - ![mdbookkit hero image](/docs/src/media/social.webp) 3 + ![mdbookkit hero image](/docs/src/media/banner.webp) 4 4 5 - [`mdbookkit`] provides quality-of-life plugins that you can use in your [mdBook] 6 - project. 5 + Quality-of-life plugins for your [mdBook] project. 7 6 8 7 Right now, there are two mdBook [preprocessors], both for generating **correct and 9 8 versioned** external links from **easy-to-write** markup. ··· 11 10 - [**`mdbook-rustdoc-link`**](https://tonywu6.github.io/mdbookkit/rustdoc-link) 12 11 13 12 _rustdoc_-style linking for Rust APIs: write types and function names, get links to 14 - docs.rs 13 + _docs.rs_ 15 14 16 15 - [**`mdbook-link-forever`**](https://tonywu6.github.io/mdbookkit/link-forever) 17 16
+1 -1
crates/mdbookkit/src/bin/rustdoc_link/env.rs
··· 88 88 /// 89 89 /// This is only meaningful if your links happen to have visible text that has 90 90 /// specific punctuation. The processor otherwise passes through the rest of your 91 - /// Markdown source. 91 + /// Markdown source untouched. 92 92 /// 93 93 /// **In `book.toml`** — this option is not needed because 94 94 /// `output.html.smart-punctuation` is honored.
+5 -6
crates/mdbookkit/tests/snaps/rustdoc_link/getting-started.snap
··· 1 1 --- 2 2 source: crates/mdbookkit/tests/rustdoc_link.rs 3 - assertion_line: 31 4 3 expression: output 5 4 --- 6 5 # Getting started ··· 9 8 10 9 ## Install 11 10 12 - You will need: 11 + You will need to: 13 12 14 - 1. [rust-analyzer]: 13 + 1. Have [rust-analyzer]: 15 14 16 - - If you already use the [VS Code extension][ra-extension], this project will 17 - automatically use the server binary that comes with it, no extra setup is needed! 15 + - If you already use the [VS Code extension][ra-extension]: this crate automatically 16 + uses the server binary that comes with it, no extra setup is needed! 18 17 - Otherwise, [install][ra-install] rust-analyzer (e.g. via `rustup`) and make sure 19 18 it's on your `PATH`. 20 19 21 - 2. This crate: 20 + 2. Install this crate: 22 21 23 22 ``` 24 23 cargo install mdbookkit --features rustdoc-link
+8 -2
crates/mdbookkit/tests/snaps/rustdoc_link/rustdoc-link.snap
··· 1 1 --- 2 2 source: crates/mdbookkit/tests/rustdoc_link.rs 3 - assertion_line: 31 4 3 expression: output 5 4 --- 6 5 # mdbook-rustdoc-link 6 + 7 + <div class="hidden"> 8 + 9 + **For best results, view this page at 10 + <https://tonywu6.github.io/mdbookkit/rustdoc-link>.** 11 + 12 + </div> 7 13 8 14 **[_rustdoc_-style linking][rustdoc] for [mdBook]** (with the help of [rust-analyzer]). 9 15 ··· 45 51 46 52 For **writing documentation** — 47 53 48 - - To know more about how the preprocessor is resolving items into links, including 54 + - To learn more about how it is resolving items into links, including 49 55 [feature-gated items](rustdoc-link/name-resolution.md#feature-gated-items), see 50 56 [Name resolution](rustdoc-link/name-resolution.md). 51 57 - To know how to link to other types of items like
+7 -7
crates/mdbookkit/tests/snaps/rustdoc_link/rustdoc-link.stderr.snap
··· 1 1 --- 2 - source: crates/rustdoc-link/tests/lib.rs 2 + source: crates/mdbookkit/tests/rustdoc_link.rs 3 3 expression: report 4 4 --- 5 5 info: successfully resolved all links 6 - ╭─[rustdoc-link:18:5] 7 - 17 │ 8 - 18 │ The [`option`][std::option] and [`result`][std::result] modules define optional and 6 + ╭─[rustdoc-link:25:5] 7 + 24 │ 8 + 25 │ The [`option`][std::option] and [`result`][std::result] modules define optional and 9 9 · ───────────┬─────────── ───────────┬─────────── 10 10 · │ ╰── https://doc.rust-lang.org/stable/core/result/index.html 11 11 · ╰── https://doc.rust-lang.org/stable/core/option/index.html 12 - 19 │ error-handling types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`][std::iter] module 12 + 26 │ error-handling types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`][std::iter] module 13 13 · ──────┬────── ────────┬─────── ─────────┬───────── 14 14 · │ │ ╰── https://doc.rust-lang.org/stable/core/iter/index.html 15 15 · │ ╰── https://doc.rust-lang.org/stable/core/result/enum.Result.html 16 16 · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 17 - 20 │ defines Rust's iterator trait, [`Iterator`], which works with the `for` loop to access 17 + 27 │ defines Rust's iterator trait, [`Iterator`], which works with the `for` loop to access 18 18 · ──────┬───── 19 19 · ╰── https://doc.rust-lang.org/stable/core/iter/traits/iterator/trait.Iterator.html 20 - 21 │ collections. [^1] 20 + 28 │ collections. [^1] 21 21 ╰────
+17 -4
crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.snap
··· 1 1 --- 2 - source: crates/rustdoc-link/tests/lib.rs 2 + source: crates/mdbookkit/tests/rustdoc_link.rs 3 3 expression: output 4 4 --- 5 5 # Supported syntax 6 6 7 + <div class="hidden"> 8 + 9 + **For best results, view this page at 10 + <https://tonywu6.github.io/mdbookkit/rustdoc-link/supported-syntax>.** 11 + 12 + </div> 13 + 7 14 This page showcases all the syntax supported by `mdbook-rustdoc-link`. 8 15 9 16 Most of the formats [supported by rustdoc][rustdoc-linking] are supported. Unsupported 10 17 syntax and differences in behavior are emphasized below. 11 18 12 - [rustdoc-linking]: 13 - https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html 14 - 15 19 In general, specifying items as you would when writing Rust code should "just work". 16 20 17 21 <details class="toc" open> ··· 28 32 - [Linking to page sections](#linking-to-page-sections) 29 33 30 34 </details> 35 + 36 + > [!TIP] 37 + > 38 + > This page is also used for snapshot testing! To see how all the links would look like 39 + > in Markdown after they have been processed, see 40 + > [supported-syntax.snap](/crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.snap) 41 + > and 42 + > [supported-syntax.stderr.snap](/crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.stderr.snap). 31 43 32 44 ## Types, modules, and associated items 33 45 ··· 262 274 [gh-issues]: https://github.com/tonywu6/mdbookkit/issues 263 275 [namespaces]: https://doc.rust-lang.org/reference/names/namespaces.html 264 276 [rust-types]: https://doc.rust-lang.org/reference/types.html#r-type.kinds 277 + [rustdoc-linking]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html 265 278 266 279 <!-- prettier-ignore-end -->
+222 -186
crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.stderr.snap
··· 1 1 --- 2 - source: crates/rustdoc-link/tests/lib.rs 2 + source: crates/mdbookkit/tests/rustdoc_link.rs 3 3 expression: report 4 4 --- 5 5 info: successfully resolved all links 6 - ╭─[supported-syntax:34:10] 7 - 33 │ > 8 - 34 │ > Module [`alloc`][std::alloc] — Memory allocation APIs. 6 + ╭─[supported-syntax:46:10] 7 + 45 │ > 8 + 46 │ > Module [`alloc`][std::alloc] — Memory allocation APIs. 9 9 · ──────────┬────────── 10 10 · ╰── https://doc.rust-lang.org/stable/std/alloc/index.html 11 - 35 │ > 12 - 36 │ > ```md 13 - 37 │ > Every [`Option`] is either [`Some`][Option::Some][^1] and contains a value, or 14 - 38 │ > [`None`][Option::None][^1], and does not. 15 - 39 │ > ``` 16 - 40 │ > 17 - 41 │ > Every [`Option`] is either [`Some`][Option::Some][^1] and contains a value, or 11 + 47 │ > 12 + 48 │ > ```md 13 + 49 │ > Every [`Option`] is either [`Some`][Option::Some][^1] and contains a value, or 14 + 50 │ > [`None`][Option::None][^1], and does not. 15 + 51 │ > ``` 16 + 52 │ > 17 + 53 │ > Every [`Option`] is either [`Some`][Option::Some][^1] and contains a value, or 18 18 · ─────┬──── ───────────┬────────── 19 19 · │ ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html#variant.Some 20 20 · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 21 - 42 │ > [`None`][Option::None][^1], and does not. 21 + 54 │ > [`None`][Option::None][^1], and does not. 22 22 · ───────────┬────────── 23 23 · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html#variant.None 24 - 43 │ > 25 - 44 │ > ```md 26 - 45 │ > [`Ipv4Addr::LOCALHOST`][core::net::Ipv4Addr::LOCALHOST] — An IPv4 address with the 27 - 46 │ > address pointing to localhost: `127.0.0.1`. 28 - 47 │ > ``` 29 - 48 │ > 30 - 49 │ > [`Ipv4Addr::LOCALHOST`][core::net::Ipv4Addr::LOCALHOST] — An IPv4 address with the 24 + 55 │ > 25 + 56 │ > ```md 26 + 57 │ > [`Ipv4Addr::LOCALHOST`][core::net::Ipv4Addr::LOCALHOST] — An IPv4 address with the 27 + 58 │ > address pointing to localhost: `127.0.0.1`. 28 + 59 │ > ``` 29 + 60 │ > 30 + 61 │ > [`Ipv4Addr::LOCALHOST`][core::net::Ipv4Addr::LOCALHOST] — An IPv4 address with the 31 31 · ───────────────────────────┬─────────────────────────── 32 32 · ╰── https://doc.rust-lang.org/stable/core/net/ip_addr/struct.Ipv4Addr.html#associatedconstant.LOCALHOST 33 - 50 │ > address pointing to localhost: `127.0.0.1`. 34 - 51 │ 35 - 52 │ ## Generic parameters 36 - 53 │ 37 - 54 │ Types can contain generic parameters. This is _compatible_ with rustdoc. 38 - 55 │ 39 - 56 │ > ```md 40 - 57 │ > [`Vec<T>`] — A heap-allocated _vector_ that is resizable at runtime. 41 - 58 │ > ``` 42 - 59 │ > 43 - 60 │ > [`Vec<T>`] — A heap-allocated _vector_ that is resizable at runtime. 33 + 62 │ > address pointing to localhost: `127.0.0.1`. 34 + 63 │ 35 + 64 │ ## Generic parameters 36 + 65 │ 37 + 66 │ Types can contain generic parameters. This is _compatible_ with rustdoc. 38 + 67 │ 39 + 68 │ > ```md 40 + 69 │ > [`Vec<T>`] — A heap-allocated _vector_ that is resizable at runtime. 41 + 70 │ > ``` 42 + 71 │ > 43 + 72 │ > [`Vec<T>`] — A heap-allocated _vector_ that is resizable at runtime. 44 44 · ─────┬──── 45 45 · ╰── https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html 46 - 61 │ > 47 - 62 │ > ```md 48 - 63 │ > | Phantom type | variance of `T` | 49 - 64 │ > | :------------------------------------------------- | :---------------- | 50 - 65 │ > | [`&'a mut T`][std::marker::PhantomData<&'a mut T>] | **inv**ariant | 51 - 66 │ > | [`fn(T)`][std::marker::PhantomData<fn(T)>] | **contra**variant | 52 - 67 │ > ``` 53 - 68 │ > 54 - 69 │ > | Phantom type | variance of `T` | 55 - 70 │ > | :------------------------------------------------- | :---------------- | 56 - 71 │ > | [`&'a mut T`][std::marker::PhantomData<&'a mut T>] | **inv**ariant | 46 + 73 │ > 47 + 74 │ > ```md 48 + 75 │ > | Phantom type | variance of `T` | 49 + 76 │ > | :------------------------------------------------- | :---------------- | 50 + 77 │ > | [`&'a mut T`][std::marker::PhantomData<&'a mut T>] | **inv**ariant | 51 + 78 │ > | [`fn(T)`][std::marker::PhantomData<fn(T)>] | **contra**variant | 52 + 79 │ > ``` 53 + 80 │ > 54 + 81 │ > | Phantom type | variance of `T` | 55 + 82 │ > | :------------------------------------------------- | :---------------- | 56 + 83 │ > | [`&'a mut T`][std::marker::PhantomData<&'a mut T>] | **inv**ariant | 57 57 · ─────────────────────────┬──────────────────────── 58 58 · ╰── https://doc.rust-lang.org/stable/core/marker/struct.PhantomData.html 59 - 72 │ > | [`fn(T)`][std::marker::PhantomData<fn(T)>] | **contra**variant | 59 + 84 │ > | [`fn(T)`][std::marker::PhantomData<fn(T)>] | **contra**variant | 60 60 · ─────────────────────┬──────────────────── 61 61 · ╰── https://doc.rust-lang.org/stable/core/marker/struct.PhantomData.html 62 - 73 │ 63 - 74 │ This includes if you use turbofish: 64 - 75 │ 65 - 76 │ > ```md 66 - 77 │ > `collect()` is one of the few times you’ll see the syntax affectionately known as the 67 - 78 │ > "turbofish", for example: [`Iterator::collect::<Vec<i32>>()`]. 68 - 79 │ > ``` 69 - 80 │ > 70 - 81 │ > `collect()` is one of the few times you’ll see the syntax affectionately known as the 71 - 82 │ > "turbofish", for example: [`Iterator::collect::<Vec<i32>>()`]. 62 + 85 │ 63 + 86 │ This includes if you use turbofish: 64 + 87 │ 65 + 88 │ > ```md 66 + 89 │ > `collect()` is one of the few times you’ll see the syntax affectionately known as the 67 + 90 │ > "turbofish", for example: [`Iterator::collect::<Vec<i32>>()`]. 68 + 91 │ > ``` 69 + 92 │ > 70 + 93 │ > `collect()` is one of the few times you’ll see the syntax affectionately known as the 71 + 94 │ > "turbofish", for example: [`Iterator::collect::<Vec<i32>>()`]. 72 72 · ─────────────────┬───────────────── 73 73 · ╰── https://doc.rust-lang.org/stable/core/iter/traits/iterator/trait.Iterator.html#method.collect 74 - 83 │ 75 - 84 │ ## Functions and macros 76 - 85 │ 77 - 86 │ To indicate that an item is a function, add `()` after the function name. To indicate 78 - 87 │ that an item is a macro, add `!` after the macro name, optionally followed by `()`, 79 - 88 │ `[]`, or `{}`. This is _compatible_ with rustdoc. 80 - 89 │ 81 - 90 │ Note that there cannot be arguments within `()`, `[]`, or `{}`. 82 - 91 │ 83 - 92 │ > ```md 84 - 93 │ > [`vec!`][std::vec!][^2] is different from [`vec`][std::vec], and don't accidentally 85 - 94 │ > use [`format()`][std::fmt::format()] in place of [`format!()`][std::format!()][^2]! 86 - 95 │ > ``` 87 - 96 │ > 88 - 97 │ > [`vec!`][std::vec!][^2] is different from [`vec`][std::vec], and don't accidentally 74 + 95 │ 75 + 96 │ ## Functions and macros 76 + 97 │ 77 + 98 │ To indicate that an item is a function, add `()` after the function name. To indicate 78 + 99 │ that an item is a macro, add `!` after the macro name, optionally followed by `()`, 79 + 100 │ `[]`, or `{}`. This is _compatible_ with rustdoc. 80 + 101 │ 81 + 102 │ Note that there cannot be arguments within `()`, `[]`, or `{}`. 82 + 103 │ 83 + 104 │ > ```md 84 + 105 │ > [`vec!`][std::vec!][^2] is different from [`vec`][std::vec], and don't accidentally 85 + 106 │ > use [`format()`][std::fmt::format()] in place of [`format!()`][std::format!()][^2]! 86 + 107 │ > ``` 87 + 108 │ > 88 + 109 │ > [`vec!`][std::vec!][^2] is different from [`vec`][std::vec], and don't accidentally 89 89 · ─────────┬───────── ────────┬──────── 90 90 · │ ╰── https://doc.rust-lang.org/stable/alloc/vec/index.html 91 91 · ╰── https://doc.rust-lang.org/stable/alloc/macros/macro.vec.html 92 - 98 │ > use [`format()`][std::fmt::format()] in place of [`format!()`][std::format!()][^2]! 92 + 110 │ > use [`format()`][std::fmt::format()] in place of [`format!()`][std::format!()][^2]! 93 93 · ────────────────┬─────────────── ──────────────┬────────────── 94 94 · │ ╰── https://doc.rust-lang.org/stable/alloc/macros/macro.format.html 95 95 · ╰── https://doc.rust-lang.org/stable/alloc/fmt/fn.format.html 96 - 99 │ 97 - 100 │ The macro syntax works for attribute and derive macros as well (even though this is not 98 - 101 │ how they are invoked). 99 - 102 │ 100 - 103 │ > ```md 101 - 104 │ > There is a [derive macro][serde::Serialize!] to generate implementations of the 102 - 105 │ > [`Serialize`][serde::Serialize] trait. 103 - 106 │ > ``` 104 - 107 │ > 105 - 108 │ > There is a [derive macro][serde::Serialize!] to generate implementations of the 96 + 111 │ 97 + 112 │ The macro syntax works for attribute and derive macros as well (even though this is not 98 + 113 │ how they are invoked). 99 + 114 │ 100 + 115 │ > ```md 101 + 116 │ > There is a [derive macro][serde::Serialize!] to generate implementations of the 102 + 117 │ > [`Serialize`][serde::Serialize] trait. 103 + 118 │ > ``` 104 + 119 │ > 105 + 120 │ > There is a [derive macro][serde::Serialize!] to generate implementations of the 106 106 · ────────────────┬──────────────── 107 107 · ╰── https://docs.rs/serde_derive/1.0.219/serde_derive/derive.Serialize.html 108 - 109 │ > [`Serialize`][serde::Serialize] trait. 108 + 121 │ > [`Serialize`][serde::Serialize] trait. 109 109 · ───────────────┬─────────────── 110 110 · ╰── https://docs.rs/serde/1.0.219/serde/ser/trait.Serialize.html 111 - 110 │ 112 - 111 │ ## Implementors and fully qualified syntax 113 - 112 │ 114 - 113 │ Trait implementors may supply additional documentation about their implementations. To 115 - 114 │ link to implemented items instead of the traits themselves, use fully qualified paths, 116 - 115 │ including `<... as Trait>` if necessary. This is a _new feature_ that rustdoc does not 117 - 116 │ currently support. 118 - 117 │ 119 - 118 │ > ```md 120 - 119 │ > [`Result<T, E>`] implements [`IntoIterator`]; its 121 - 120 │ > [**`into_iter()`**][Result::<(), ()>::into_iter] returns an iterator that yields one 122 - 121 │ > value if the result is [`Result::Ok`], otherwise none. 123 - 122 │ > 124 - 123 │ > [`Vec<T>`] also implements [`IntoIterator`]; a vector cannot be used after you call 125 - 124 │ > [**`into_iter()`**][<Vec<()> as IntoIterator>::into_iter]. 126 - 125 │ > ``` 127 - 126 │ > 128 - 127 │ > [`Result<T, E>`] implements [`IntoIterator`]; its 111 + 122 │ 112 + 123 │ ## Implementors and fully qualified syntax 113 + 124 │ 114 + 125 │ Trait implementors may supply additional documentation about their implementations. To 115 + 126 │ link to implemented items instead of the traits themselves, use fully qualified paths, 116 + 127 │ including `<... as Trait>` if necessary. This is a _new feature_ that rustdoc does not 117 + 128 │ currently support. 118 + 129 │ 119 + 130 │ > ```md 120 + 131 │ > [`Result<T, E>`] implements [`IntoIterator`]; its 121 + 132 │ > [**`into_iter()`**][Result::<(), ()>::into_iter] returns an iterator that yields one 122 + 133 │ > value if the result is [`Result::Ok`], otherwise none. 123 + 134 │ > 124 + 135 │ > [`Vec<T>`] also implements [`IntoIterator`]; a vector cannot be used after you call 125 + 136 │ > [**`into_iter()`**][<Vec<()> as IntoIterator>::into_iter]. 126 + 137 │ > ``` 127 + 138 │ > 128 + 139 │ > [`Result<T, E>`] implements [`IntoIterator`]; its 129 129 · ────────┬─────── ────────┬─────── 130 130 · │ ╰── https://doc.rust-lang.org/stable/core/iter/traits/collect/trait.IntoIterator.html 131 131 · ╰── https://doc.rust-lang.org/stable/core/result/enum.Result.html 132 - 128 │ > [**`into_iter()`**][Result::<(), ()>::into_iter] returns an iterator that yields one 132 + 140 │ > [**`into_iter()`**][Result::<(), ()>::into_iter] returns an iterator that yields one 133 133 · ────────────────────────┬─────────────────────── 134 134 · ╰── https://doc.rust-lang.org/stable/core/result/enum.Result.html#method.into_iter 135 - 129 │ > value if the result is [`Result::Ok`], otherwise none. 135 + 141 │ > value if the result is [`Result::Ok`], otherwise none. 136 136 · ───────┬────── 137 137 · ╰── https://doc.rust-lang.org/stable/core/result/enum.Result.html#variant.Ok 138 - 130 │ > 139 - 131 │ > [`Vec<T>`] also implements [`IntoIterator`]; a vector cannot be used after you call 138 + 142 │ > 139 + 143 │ > [`Vec<T>`] also implements [`IntoIterator`]; a vector cannot be used after you call 140 140 · ─────┬──── ────────┬─────── 141 141 · │ ╰── https://doc.rust-lang.org/stable/core/iter/traits/collect/trait.IntoIterator.html 142 142 · ╰── https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html 143 - 132 │ > [**`into_iter()`**][<Vec<()> as IntoIterator>::into_iter]. 143 + 144 │ > [**`into_iter()`**][<Vec<()> as IntoIterator>::into_iter]. 144 144 · ────────────────────────────┬──────────────────────────── 145 145 · ╰── https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html#method.into_iter 146 - 133 │ 147 - 134 │ > [!NOTE] 148 - 135 │ > 149 - 136 │ > If your type has generic parameters, you must supply concrete types for them for 150 - 137 │ > rust-analyzer to be able to locate an implementation. That is, `Result<T, E>` won't 151 - 138 │ > work, but `Result<(), ()>` will (unless there happen to be types `T` and `E` literally 152 - 139 │ > in scope). 153 - 140 │ 154 - 141 │ ## Disambiguators 155 - 142 │ 156 - 143 │ rustdoc's [disambiguator syntax][disambiguator] `prefix@name` is **accepted but 157 - 144 │ ignored**: 158 146 145 │ 159 - 146 │ > ```md 160 - 147 │ > [`std::vec`], [`mod@std::vec`], and [`macro@std::vec`] all link to the `vec` _module_. 161 - 148 │ > ``` 162 - 149 │ > 163 - 150 │ > [`std::vec`], [`mod@std::vec`], and [`macro@std::vec`] all link to the `vec` > 147 + 146 │ > [!NOTE] 148 + 147 │ > 149 + 148 │ > If your type has generic parameters, you must supply concrete types for them for 150 + 149 │ > rust-analyzer to be able to locate an implementation. That is, `Result<T, E>` won't 151 + 150 │ > work, but `Result<(), ()>` will (unless there happen to be types `T` and `E` literally 152 + 151 │ > in scope). 153 + 152 │ 154 + 153 │ ## Disambiguators 155 + 154 │ 156 + 155 │ rustdoc's [disambiguator syntax][disambiguator] `prefix@name` is **accepted but 157 + 156 │ ignored**: 158 + 157 │ 159 + 158 │ > ```md 160 + 159 │ > [`std::vec`], [`mod@std::vec`], and [`macro@std::vec`] all link to the `vec` _module_. 161 + 160 │ > ``` 162 + 161 │ > 163 + 162 │ > [`std::vec`], [`mod@std::vec`], and [`macro@std::vec`] all link to the `vec` > 164 164 · ──────┬───── ────────┬─────── ─────────┬──────── 165 165 · │ │ ╰── https://doc.rust-lang.org/stable/alloc/vec/index.html 166 166 · │ ╰── https://doc.rust-lang.org/stable/alloc/vec/index.html 167 167 · ╰── https://doc.rust-lang.org/stable/alloc/vec/index.html 168 - 151 │ > _module_. 169 - ╰──── 170 - ╭─[supported-syntax:191:3] 171 - 190 │ > 172 - 191 │ > [The Option type](std::option::Option) 173 - · ───────────────────┬────────────────── 174 - · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 168 + 163 │ > _module_. 169 + 164 │ 170 + 165 │ Currently, duplicate names in Rust are allowed only if they correspond to items in 171 + 166 │ different [namespaces], for example, between macros and modules, and between struct 172 + 167 │ fields and methods — this is mostly covered by the function and macro syntax, described 173 + 168 │ [above](#functions-and-macros). 174 + 169 │ 175 + 170 │ If you encounter items that must be disambiguated using rustdoc's disambiguator syntax, 176 + 171 │ other than [the "special types" listed below](#special-types), please [file an 177 + 172 │ issue][gh-issues]! 178 + 173 │ 179 + 174 │ ## Special types 180 + 175 │ 181 + 176 │ > [!WARNING] 182 + 177 │ 183 + 178 │ There is **no support** on types whose syntax is not a path; they are currently not 184 + 179 │ parsed at all: 185 + 180 │ 186 + 181 │ > references `&T`, slices `[T]`, arrays `[T; N]`, tuples `(T1, T2)`, pointers like 187 + 182 │ > `*const T`, trait objects like `dyn Any`, and the never type `!` 188 + 183 │ 189 + 184 │ Note that such types can still be used as generic params, just not as standalone types. 190 + 185 │ 191 + 186 │ ## Struct fields 192 + 187 │ 193 + 188 │ > [!WARNING] 194 + 189 │ 195 + 190 │ Linking to struct fields is **not supported** yet. This is **incompatible** with 196 + 191 │ rustdoc. 175 197 192 │ 176 - 193 │ Linking with reusable references: 198 + 193 │ ## Markdown link syntax 177 199 194 │ 178 - 195 │ > ```md 179 - 196 │ > [The Option type][option-type] 180 - 197 │ > 181 - 198 │ > [option-type]: std::option::Option 182 - 199 │ > ``` 183 - 200 │ > 184 - 201 │ > [The Option type][option-type] 185 - · ───────────────┬────────────── 186 - · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 200 + 195 │ All Markdown link formats supported by rustdoc are supported: 201 + 196 │ 202 + 197 │ Linking with URL inlined: 203 + 198 │ 204 + 199 │ > ```md 205 + 200 │ > [The Option type](std::option::Option) 206 + 201 │ > ``` 187 207 202 │ > 188 - 203 │ > [option-type]: std::option::Option 208 + 203 │ > [The Option type](std::option::Option) 209 + · ───────────────────┬────────────────── 210 + · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 189 211 204 │ 190 - 205 │ Reference-style links `[text][id]` without a corresponding `[id]: name` part will be 191 - 206 │ treated the same as inline-style links `[text](id)`: 192 - 207 │ 193 - 208 │ > ```md 194 - 209 │ > [The Option type][std::option::Option] 195 - 210 │ > ``` 196 - 211 │ > 197 - 212 │ > [The Option type][std::option::Option] 212 + 205 │ Linking with reusable references: 213 + 206 │ 214 + 207 │ > ```md 215 + 208 │ > [The Option type][option-type] 216 + 209 │ > 217 + 210 │ > [option-type]: std::option::Option 218 + 211 │ > ``` 219 + 212 │ > 220 + 213 │ > [The Option type][option-type] 221 + · ───────────────┬────────────── 222 + · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 223 + 214 │ > 224 + 215 │ > [option-type]: std::option::Option 225 + 216 │ 226 + 217 │ Reference-style links `[text][id]` without a corresponding `[id]: name` part will be 227 + 218 │ treated the same as inline-style links `[text](id)`: 228 + 219 │ 229 + 220 │ > ```md 230 + 221 │ > [The Option type][std::option::Option] 231 + 222 │ > ``` 232 + 223 │ > 233 + 224 │ > [The Option type][std::option::Option] 198 234 · ───────────────────┬────────────────── 199 235 · ╰── https://doc.rust-lang.org/stable/core/option/enum.Option.html 200 - 213 │ 201 - 214 │ Shortcuts are supported, and can contain inline markups: 202 - 215 │ 203 - 216 │ > ```md 204 - 217 │ > You can create a [`Vec`] with [**`Vec::new`**], or by using the [_`vec!`_][^2] macro. 205 - 218 │ > ``` 206 - 219 │ > 207 - 220 │ > You can create a [`Vec`] with [**`Vec::new`**], or by using the [_`vec!`_][^2] macro. 236 + 225 │ 237 + 226 │ Shortcuts are supported, and can contain inline markups: 238 + 227 │ 239 + 228 │ > ```md 240 + 229 │ > You can create a [`Vec`] with [**`Vec::new`**], or by using the [_`vec!`_][^2] macro. 241 + 230 │ > ``` 242 + 231 │ > 243 + 232 │ > You can create a [`Vec`] with [**`Vec::new`**], or by using the [_`vec!`_][^2] macro. 208 244 · ───┬─── ────────┬─────── ─────┬──── 209 245 · │ │ ╰── https://doc.rust-lang.org/stable/alloc/macros/macro.vec.html 210 246 · │ ╰── https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html#method.new 211 247 · ╰── https://doc.rust-lang.org/stable/alloc/vec/struct.Vec.html 212 - 221 │ 213 - 222 │ (The items must still be resolvable; in this case `Vec` and `vec!` come from the 214 - 223 │ prelude.) 215 - 224 │ 216 - 225 │ ## Linking to page sections 217 - 226 │ 218 - 227 │ To link to a known section on a page, use a URL fragment, just like a normal link. This 219 - 228 │ is _compatible_ with rustdoc. 220 - 229 │ 221 - 230 │ <!-- prettier-ignore-start --> 222 - 231 │ 223 - 232 │ > ```md 224 - 233 │ > [When Should You Use Which Collection?][std::collections#when-should-you-use-which-collection] 225 - 234 │ > ``` 226 - 235 │ > 227 - 236 │ > [When Should You Use Which Collection?][std::collections#when-should-you-use-which-collection] 248 + 233 │ 249 + 234 │ (The items must still be resolvable; in this case `Vec` and `vec!` come from the 250 + 235 │ prelude.) 251 + 236 │ 252 + 237 │ ## Linking to page sections 253 + 238 │ 254 + 239 │ To link to a known section on a page, use a URL fragment, just like a normal link. This 255 + 240 │ is _compatible_ with rustdoc. 256 + 241 │ 257 + 242 │ <!-- prettier-ignore-start --> 258 + 243 │ 259 + 244 │ > ```md 260 + 245 │ > [When Should You Use Which Collection?][std::collections#when-should-you-use-which-collection] 261 + 246 │ > ``` 262 + 247 │ > 263 + 248 │ > [When Should You Use Which Collection?][std::collections#when-should-you-use-which-collection] 228 264 · ───────────────────────────────────────────────┬────────────────────────────────────────────── 229 265 · ╰── https://doc.rust-lang.org/stable/std/collections/index.html 230 - 237 │ 231 - 238 │ <!-- prettier-ignore-end --> 232 - 239 │ 233 - 240 │ --- 234 - 241 │ 235 - 242 │ [^1]: 236 - 243 │ rust-analyzer's ability to generate links for enum variants like `Option::Some` was 237 - 244 │ improved only somewhat recently: before 238 - 245 │ [#19246](https://github.com/rust-lang/rust-analyzer/pull/19246), links for variants 239 - 246 │ and associated items may only point to the types themselves. If linking to such 240 - 247 │ items doesn't seem to work for you, be sure to upgrade to a newer rust-analyzer 241 - 248 │ first! 242 266 249 │ 243 - 250 │ [^2]: 244 - 251 │ As of rust-analyzer <ra-version>(version)</ra-version>, links generated for macros 245 - 252 │ don't always work. Examples include [`std::format!`] (seen above) and 267 + 250 │ <!-- prettier-ignore-end --> 268 + 251 │ 269 + 252 │ --- 270 + 253 │ 271 + 254 │ [^1]: 272 + 255 │ rust-analyzer's ability to generate links for enum variants like `Option::Some` was 273 + 256 │ improved only somewhat recently: before 274 + 257 │ [#19246](https://github.com/rust-lang/rust-analyzer/pull/19246), links for variants 275 + 258 │ and associated items may only point to the types themselves. If linking to such 276 + 259 │ items doesn't seem to work for you, be sure to upgrade to a newer rust-analyzer 277 + 260 │ first! 278 + 261 │ 279 + 262 │ [^2]: 280 + 263 │ As of rust-analyzer <ra-version>(version)</ra-version>, links generated for macros 281 + 264 │ don't always work. Examples include [`std::format!`] (seen above) and 246 282 · ────────┬─────── 247 283 · ╰── https://doc.rust-lang.org/stable/alloc/macros/macro.format.html 248 - 253 │ [`tokio::main!`]. For more info, see [Known issues](known-issues.md#macros). 284 + 265 │ [`tokio::main!`]. For more info, see [Known issues](known-issues.md#macros). 249 285 · ────────┬─────── 250 286 · ╰── https://docs.rs/tokio-macros/2.5.0/tokio_macros/macro.main.html 251 - 254 │ 287 + 266 │ 252 288 ╰────
+1 -9
docs/app/main.css
··· 91 91 margin-block-start: 2.5rem; 92 92 } 93 93 94 - /* 95 - h1 + h2, 96 - h2 + h3, 97 - h3 + h4, 98 - h4 + h5 { 99 - margin-block-start: 1rem; 100 - } */ 101 - 102 94 h2, 103 95 h3, 104 96 h4, ··· 255 247 img, 256 248 video { 257 249 max-width: 100%; 250 + max-height: 100%; 258 251 height: auto; 259 252 object-fit: contain; 260 253 } ··· 280 273 } 281 274 282 275 > p { 283 - display: contents; 284 276 margin: 0; 285 277 } 286 278
docs/app/socials.pxd

This is a binary file and will not be displayed.

docs/src/media/banner.webp

This is a binary file and will not be displayed.

+8 -1
docs/src/rustdoc-link.md
··· 1 1 # mdbook-rustdoc-link 2 2 3 + <div class="hidden"> 4 + 5 + **For best results, view this page at 6 + <https://tonywu6.github.io/mdbookkit/rustdoc-link>.** 7 + 8 + </div> 9 + 3 10 **[_rustdoc_-style linking][rustdoc] for [mdBook]** (with the help of [rust-analyzer]). 4 11 5 12 You write: ··· 40 47 41 48 For **writing documentation** — 42 49 43 - - To know more about how the preprocessor is resolving items into links, including 50 + - To learn more about how it is resolving items into links, including 44 51 [feature-gated items](rustdoc-link/name-resolution.md#feature-gated-items), see 45 52 [Name resolution](rustdoc-link/name-resolution.md). 46 53 - To know how to link to other types of items like
+1 -1
docs/src/rustdoc-link/caching.md
··· 30 30 ```toml 31 31 [preprocessor.rustdoc-link] 32 32 cache-dir = "cache" 33 - # You can also point to an arbitrary directory in target/ 33 + # You could also point to an arbitrary directory in target/ 34 34 ``` 35 35 36 36 Now, when `mdbook` rebuilds your book during `build` or `serve`, the preprocessor reuses
+5 -5
docs/src/rustdoc-link/getting-started.md
··· 4 4 5 5 ## Install 6 6 7 - You will need: 7 + You will need to: 8 8 9 - 1. [rust-analyzer]: 9 + 1. Have [rust-analyzer]: 10 10 11 - - If you already use the [VS Code extension][ra-extension], this project will 12 - automatically use the server binary that comes with it, no extra setup is needed! 11 + - If you already use the [VS Code extension][ra-extension]: this crate automatically 12 + uses the server binary that comes with it, no extra setup is needed! 13 13 - Otherwise, [install][ra-install] rust-analyzer (e.g. via `rustup`) and make sure 14 14 it's on your `PATH`. 15 15 16 - 2. This crate: 16 + 2. Install this crate: 17 17 18 18 ``` 19 19 cargo install mdbookkit --features rustdoc-link
+2 -3
docs/src/rustdoc-link/motivation.md
··· 11 11 12 12 - APIs are mentioned without linking to reference docs. 13 13 14 - This is probably fine for tutorials and examples, but it does mean a reduced 15 - connection between guide-level text and usage details. Readers won't be able to 16 - navigate from one to the other as easily. 14 + This is probably fine for tutorials and examples, but it does mean readers of your 15 + docs won't be able to move from guides to references as easily. 17 16 18 17 - You do want at least some cross-references, but it is cumbersome to find and copy the 19 18 correct links, and even more so to maintain them.
+3 -4
docs/src/rustdoc-link/name-resolution.md
··· 6 6 7 7 > [!TIP] 8 8 > 9 - > If you use Cargo workspaces, or if your source tree has special layouts, see 9 + > If you use Cargo workspaces, or if your source tree has special layout, see 10 10 > [Workspace layout](workspace-layout.md) for more information. 11 11 12 12 An item must be **in scope in the entrypoint** for the proprocessor to generate a link ··· 93 93 ## Feature-gated items 94 94 95 95 To link to items that are gated behind features, use the 96 - [`cargo-features`](configuration.md#cargo-features) option. 96 + [`cargo-features`](configuration.md#cargo-features) option in `book.toml`. 97 97 98 98 For example, [clap] is known for providing guide-level documentation through docs.rs. 99 99 The tutorial for its Derive API is gated behind the `unstable-doc` feature. To link to ··· 114 114 115 115 ## Which entrypoint 116 116 117 - The "entrypoint" is usually `src/lib.rs` or `src/main.rs`. 117 + For this preprocessor, the "entrypoint" is usually `src/lib.rs` or `src/main.rs`. 118 118 119 119 - If your crate has multiple `bin` targets, it will use the first one listed in your 120 120 `Cargo.toml`. ··· 174 174 <figure id="media-open-docs"> 175 175 <img src="media/open-docs.png" alt="the Open Docs option in VS Code"> 176 176 </figure> 177 - 178 177 <style> 179 178 @media screen and (min-width: 768px) { 180 179 #media-open-docs {
+1 -2
docs/src/rustdoc-link/standalone-usage.md
··· 14 14 `book.toml`, such as [`--cache-dir`](configuration.md#cache-dir). Run 15 15 `mdbook-rustdoc-link markdown --help` to see them. 16 16 17 - Use it in any text processing pipeline! 18 - 19 17 <figure id="media-open-docs"> 20 18 <img src="media/standalone-usage.png" alt="example using mdbook-rustdoc-link as a command line tool"> 19 + <figcaption>Use it in any text processing pipeline!</figcaption> 21 20 </figure> 22 21 23 22 <style>
+16 -3
docs/src/rustdoc-link/supported-syntax.md
··· 1 1 # Supported syntax 2 2 3 + <div class="hidden"> 4 + 5 + **For best results, view this page at 6 + <https://tonywu6.github.io/mdbookkit/rustdoc-link/supported-syntax>.** 7 + 8 + </div> 9 + 3 10 This page showcases all the syntax supported by `mdbook-rustdoc-link`. 4 11 5 12 Most of the formats [supported by rustdoc][rustdoc-linking] are supported. Unsupported 6 13 syntax and differences in behavior are emphasized below. 7 14 8 - [rustdoc-linking]: 9 - https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html 10 - 11 15 In general, specifying items as you would when writing Rust code should "just work". 12 16 13 17 <details class="toc" open> ··· 24 28 - [Linking to page sections](#linking-to-page-sections) 25 29 26 30 </details> 31 + 32 + > [!TIP] 33 + > 34 + > This page is also used for snapshot testing! To see how all the links would look like 35 + > in Markdown after they have been processed, see 36 + > [supported-syntax.snap](/crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.snap) 37 + > and 38 + > [supported-syntax.stderr.snap](/crates/mdbookkit/tests/snaps/rustdoc_link/supported-syntax.stderr.snap). 27 39 28 40 ## Types, modules, and associated items 29 41 ··· 258 270 [gh-issues]: https://github.com/tonywu6/mdbookkit/issues 259 271 [namespaces]: https://doc.rust-lang.org/reference/names/namespaces.html 260 272 [rust-types]: https://doc.rust-lang.org/reference/types.html#r-type.kinds 273 + [rustdoc-linking]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html 261 274 262 275 <!-- prettier-ignore-end -->