Rollup merge of rust-lang#110641 - GuillaumeGomez:rustdoc-in-doc-sett…

…ings, r=notriddle

Add new rustdoc book chapter to describe in-doc settings

Fixes rust-lang#55165.

I continue going through old rustdoc issues. This one made a lot of sense so decided to add the missing chapter.

r? `@notriddle`

src/doc/rustdoc/src/SUMMARY.md

@@ -3,6 +3,7 @@
 - [What is rustdoc?](what-is-rustdoc.md)
 - [Command-line arguments](command-line-arguments.md)
 - [How to read rustdoc output](how-to-read-rustdoc.md)
+    - [In-doc settings](read-documentation/in-doc-settings.md)
 - [How to write documentation](how-to-write-documentation.md)
     - [What to include (and exclude)](write-documentation/what-to-include.md)
     - [The `#[doc]` attribute](write-documentation/the-doc-attribute.md)

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

@@ -68,7 +68,7 @@ Typing in the search bar instantly searches the available documentation for
 the string entered with a fuzzy matching algorithm that is tolerant of minor
 typos.
 
-By default, the search results give are "In Names",
+By default, the search results given are "In Names",
 meaning that the fuzzy match is made against the names of items.
 Matching names are shown on the left, and the first few words of their
 descriptions are given on the right.
@@ -105,11 +105,6 @@ will match these queries:
 
 But it *does not* match `Result<Vec, u8>` or `Result<u8<Vec>>`.
 
-### Changing displayed theme
-
-You can change the displayed theme by opening the settings menu (the gear
-icon in the upper right) and then pick a new one from there.
-
 ### Shortcuts
 
 Pressing `S` while focused elsewhere on the page will move focus to the

src/doc/rustdoc/src/read-documentation/in-doc-settings.md

@@ -0,0 +1,64 @@
+# Rustdoc in-doc settings
+
+Rustdoc's HTML output includes a settings menu, and this chapter describes what
+each setting in this menu does.
+
+It can be accessed by clicking on the gear button
+(<i class="fa fa-cog" aria-hidden="true"></i>) in the upper right.
+
+## Changing displayed theme
+
+It is possible to change the theme. If you pick the "system preference", you
+will be able to see two new sub-menus: "Preferred light theme" and "Preferred
+dark theme". It means that if your system preference is set to "light", then
+rustdoc will use the theme you selected in "Preferred light theme".
+
+## Auto-hide item contents for large items
+
+If the type definition contains more than 12 items, and this setting is enabled,
+it'll collapse them by default. You can see them by clicking on the `[+]` button
+to expand them.
+
+A good example of this setting in use can be seen in the
+[`Iterator`](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html) doc
+page:
+
+![Collapsed long item](../images/collapsed-long-item.png)
+
+## Auto-hide item methods' documentation
+
+If enabled, this setting will collapse all trait implementations blocks. It is
+convenient if you just want an overview of all the methods available. You can
+still see a method's documentation by expanding it.
+
+## Auto-hide trait implementation documentation
+
+If enabled, this setting will collapse all trait implementations blocks (you can
+see them in the "Trait Implementations" section). It is convenient if you just
+want an overview of all the trait implemented on a type. You can still see
+a trait implementation's associated items by expanding it.
+
+Example:
+
+![Collapsed trait implementations](../images/collapsed-trait-impls.png)
+
+## Directly go to item in search if there is only one result
+
+If this setting is enabled, you will directly be taken to the result page if
+your search only returned one element. Useful if you know exactly what you're
+looking for and want to be taken there directly and not waste time selecting the
+only search result.
+
+## Show line numbers on code examples
+
+If enabled, this setting will add line numbers to the code examples in the
+documentation. It provides a visual aide for the code reading.
+
+## Disable keyboard shortcuts
+
+If this setting is enabled, the keyboard shortcuts will be disabled. It's useful
+in case some of these shortcuts are already used by a web extension you're
+using.
+
+To see the full list of the rustdoc keyboard shortcuts, you can open the help
+menu (the button with the question mark on the left of the setting menu button).