Rollup merge of rust-lang#94753 - Urgau:rustdoc-book-improvements, r=GuillaumeGomez

Improve rustdoc book

This pull-request improves the `rustdoc` book by doing some (light) cleanup, by merging some stuff, by adding some missing stuff (like tracking issues links, for those who had one) and also by moving some chapter's into sub-chapter's to improve the flow of the book.

~~Note that I locally tested with `mdbook-lintcheck` that no links became accidentally broken.~~ (Not enough, ;-))

r? ```@GuillaumeGomez```

Author: Dylan-DPC

src/doc/rustdoc/book.toml

@@ -4,3 +4,7 @@ title = "The rustdoc book"
 
 [output.html]
 git-repository-url = "https://github.com/rust-lang/rust/tree/master/src/doc/rustdoc"
+
+[output.html.redirect]
+"/the-doc-attribute.html" = "write-documentation/the-doc-attribute.html"
+"/documentation-tests.html" = "write-documentation/documentation-tests.html"

src/doc/rustdoc/src/SUMMARY.md

@@ -1,16 +1,15 @@
 # The Rustdoc Book
 
 - [What is rustdoc?](what-is-rustdoc.md)
+- [Command-line arguments](command-line-arguments.md)
 - [How to read rustdoc output](how-to-read-rustdoc.md)
 - [How to write documentation](how-to-write-documentation.md)
-- [What to include (and exclude)](what-to-include.md)
-- [Command-line arguments](command-line-arguments.md)
-- [The `#[doc]` attribute](the-doc-attribute.md)
-- [Documentation tests](documentation-tests.md)
-- [Linking to items by name](linking-to-items-by-name.md)
-- [Lints](lints.md)
+    - [What to include (and exclude)](write-documentation/what-to-include.md)
+    - [The `#[doc]` attribute](write-documentation/the-doc-attribute.md)
+    - [Linking to items by name](write-documentation/linking-to-items-by-name.md)
+    - [Documentation tests](write-documentation/documentation-tests.md)
+- [Rustdoc-specific lints](lints.md)
 - [Advanced features](advanced-features.md)
 - [Unstable features](unstable-features.md)
-- [Website features](website-features.md)
-- [Passes](passes.md)
+- [Deprecated features](deprecated-features.md)
 - [References](references.md)

src/doc/rustdoc/src/advanced-features.md

@@ -88,3 +88,25 @@ You can add multiple aliases at the same time by using a list:
 #[doc(alias("x", "big"))]
 pub struct BigX;
 ```
+
+## Custom search engines
+
+If you find yourself often referencing online Rust docs you might enjoy using a custom search
+engine. This allows you to use the navigation bar directly to search a `rustdoc` website.
+Most browsers support this feature by letting you define a URL template containing `%s`
+which will be substituted for the search term. As an example, for the standard library you could use
+this template:
+
+```text
+https://doc.rust-lang.org/stable/std/?search=%s
+```
+
+Note that this will take you to a results page listing all matches. If you want to navigate to the first
+result right away (which is often the best match) use the following instead:
+
+```text
+https://doc.rust-lang.org/stable/std/?search=%s&go_to_first=true
+```
+
+This URL adds the `go_to_first=true` query parameter which can be appended to any `rustdoc` search URL
+to automatically go to the first result.

src/doc/rustdoc/src/command-line-arguments.md

@@ -177,7 +177,7 @@ $ rustdoc src/lib.rs --test
 ```
 
 This flag will run your code examples as tests. For more, see [the chapter
-on documentation tests](documentation-tests.md).
+on documentation tests](write-documentation/documentation-tests.md).
 
 See also `--test-args`.
 
@@ -190,7 +190,7 @@ $ rustdoc src/lib.rs --test --test-args ignored
 ```
 
 This flag will pass options to the test runner when running documentation tests.
-For more, see [the chapter on documentation tests](documentation-tests.md).
+For more, see [the chapter on documentation tests](write-documentation/documentation-tests.md).
 
 See also `--test`.
 
@@ -336,7 +336,7 @@ $ rustdoc src/lib.rs --sysroot /path/to/sysroot
 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
 when compiling your code.
 
-### `--edition`: control the edition of docs and doctests
+## `--edition`: control the edition of docs and doctests
 
 Using this flag looks like this:
 
@@ -403,12 +403,12 @@ encoded as UTF-8.
 ## `--passes`: add more rustdoc passes
 
 This flag is **deprecated**.
-For more details on passes, see [the chapter on them](passes.md).
+For more details on passes, see [the chapter on them](deprecated-features.md#passes).
 
 ## `--no-defaults`: don't run default passes
 
 This flag is **deprecated**.
-For more details on passes, see [the chapter on them](passes.md).
+For more details on passes, see [the chapter on them](deprecated-features.md#passes).
 
 ## `-r`/`--input-format`: input format
 
@@ -417,23 +417,3 @@ This flag is **deprecated** and **has no effect**.
 Rustdoc only supports Rust source code and Markdown input formats. If the
 file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
 Otherwise, it assumes that the input file is Rust.
-
-# Unstable command line arguments
-
-## `--nocapture`
-
-When this flag is used with `--test`, the output (stdout and stderr) of your tests won't be
-captured by rustdoc. Instead, the output will be directed to your terminal,
-as if you had run the test executable manually. This is especially useful
-for debugging your tests!
-
-## `--check`
-
-When this flag is supplied, rustdoc will type check and lint your code, but will not generate any
-documentation or run your doctests.
-
-Using this flag looks like:
-
-```bash
-rustdoc -Z unstable-options --check src/lib.rs
-```

src/doc/rustdoc/src/passes.md renamed to src/doc/rustdoc/src/deprecated-features.md

@@ -1,4 +1,6 @@
-# Passes
+# Deprecated features
+
+## Passes
 
 Rustdoc has a concept called "passes". These are transformations that
 `rustdoc` runs on your documentation before producing its final output.

src/doc/rustdoc/src/how-to-read-rustdoc.md

@@ -26,7 +26,7 @@ At the top is some at-a-glance info and controls:
 - a button to collapse or expand the top-level documentation for that item
   (`[+]` or `[-]`),
 - a link to the source code (`[src]`),
-  if [configured](the-doc-attribute.html#html_no_source),
+  if [configured](write-documentation/the-doc-attribute.html#html_no_source),
   and present (the source may not be available if
   the documentation was created with `cargo doc --no-deps`),
 - and the version in which the item became stable,
@@ -52,7 +52,7 @@ For example, when looking at documentation for the crate root,
 it shows all the crates documented in the documentation bundle,
 and quick links to the modules, structs, traits, functions, and macros available
 from the current crate.
-At the top, it displays a [configurable logo](the-doc-attribute.html#html_logo_url)
+At the top, it displays a [configurable logo](write-documentation/the-doc-attribute.html#html_logo_url)
 alongside the current crate's name and version,
 or the current item whose documentation is being displayed.
 

src/doc/rustdoc/src/lints.md

@@ -13,11 +13,11 @@ Note that, except for `missing_docs`, these lints are only available when runnin
 
 Here is the list of the lints provided by `rustdoc`:
 
-## broken_intra_doc_links
+## `broken_intra_doc_links`
 
 This lint **warns by default**. This lint detects when an [intra-doc link] fails to be resolved. For example:
 
-[intra-doc link]: linking-to-items-by-name.md
+[intra-doc link]: write-documentation/linking-to-items-by-name.md
 
 ```rust
 /// I want to link to [`Nonexistent`] but it doesn't exist!
@@ -64,7 +64,7 @@ help: to link to the function, add parentheses
 
 ```
 
-## private_intra_doc_links
+## `private_intra_doc_links`
 
 This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
 For example:
@@ -104,9 +104,9 @@ warning: public documentation for `public` links to private item `private`
   = note: this link resolves only because you passed `--document-private-items`, but will break without
 ```
 
-[intra-doc links]: linking-to-items-by-name.html
+[intra-doc links]: write-documentation/linking-to-items-by-name.md
 
-## missing_docs
+## `missing_docs`
 
 This lint is **allowed by default**. It detects items missing documentation.
 For example:
@@ -130,7 +130,7 @@ warning: missing documentation for a function
 
 Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
 
-## missing_crate_level_docs
+## `missing_crate_level_docs`
 
 This lint is **allowed by default**. It detects if there is no documentation
 at the crate root. For example:
@@ -154,7 +154,7 @@ warning in the future. This is intended as a means to introduce new users on
 get started, without providing overwhelming warnings like `missing_docs`
 might.
 
-## missing_doc_code_examples
+## `missing_doc_code_examples`
 
 This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
 is missing a code example. For example:
@@ -190,7 +190,7 @@ To fix the lint, you need to add a code example into the documentation block:
 pub fn no_code_example() {}
 ```
 
-## private_doc_tests
+## `private_doc_tests`
 
 This lint is **allowed by default**. It detects documentation tests when they
 are on a private item. For example:
@@ -223,7 +223,7 @@ warning: Documentation test in private item
    | |___________^
 ```
 
-## invalid_codeblock_attributes
+## `invalid_codeblock_attributes`
 
 This lint **warns by default**. It detects code block attributes in
 documentation examples that have potentially mis-typed values. For example:
@@ -259,7 +259,7 @@ warning: unknown attribute `should-panic`. Did you mean `should_panic`?
 In the example above, the correct form is `should_panic`. This helps detect
 typo mistakes for some common attributes.
 
-## invalid_html_tags
+## `invalid_html_tags`
 
 This lint is **allowed by default** and is **nightly-only**. It detects unclosed
 or invalid HTML tags. For example:
@@ -298,7 +298,7 @@ warning: unclosed HTML tag `h1`
 warning: 2 warnings emitted
 ```
 
-## invalid_rust_codeblocks
+## `invalid_rust_codeblocks`
 
 This lint **warns by default**. It detects Rust code blocks in documentation
 examples that are invalid (e.g. empty, not parsable as Rust). For example:
@@ -342,7 +342,7 @@ warning: could not parse code block as Rust code
    = note: error from rustc: unterminated character literal
 ```
 
-## bare_urls
+## `bare_urls`
 
 This lint is **warn-by-default**. It detects URLs which are not links.
 For example: