rustdoc: add a list of headings to the sidebar
It's another misdreavus rustdoc PR, which means it's time for Bikeshed City once again! `:3`
In an effort to aid navigation in long documentation pages, this PR adds a listing of headings to the sidebars of pages where such headings exist. For example, for structs, links to their fields, inherent methods, and trait implementations are available where applicable.
Examples:
* Modules/Crate roots
* Enums
* Primitives
* Traits
* Structs
Open questions:
* Right now, these kinds of pages (and also unions) are the only pages that will receive the name header - pages for functions, constants, macros, etc, won't have the corresponding name in their sidebar. Should I print the name regardless and only add table-of-contents links for pages that have them? This would make them match, for example, a struct with no public fields, no methods, and no trait implementations. The latter would still have a "Struct MyStruct" line above the module contents, with no header links to speak of, whereas a function wouldn't even have "Function my\_function".
* This is only a header listing, but there has been requests to include a more-complete listing of fields/methods/traits/etc, for example in #41123.
Instead of rendering all of the HTML in rustdoc this relies on
pulldown-cmark's `push_html` to do most of the work. A few iterator
adapters are used to make rustdoc specific modifications to the output.
This also fixes MarkdownHtml and link titles in plain_summary_line.
Fix for #39596: sort Trait2 before Trait10.
This is a change discussed in #39596. Essentially, item names will be sorted as if they're (&str, u64) pairs instead of just `&str`, meaning that `"Apple" < "Banana"` and also `"Fruit10" > "Fruit2"`.
Sample sorting:
1. Apple
2. Banana
3. Fruit
4. Fruit0
5. Fruit00
6. Fruit1
7. Fruit01
8. Fruit2
9. Fruit02
10. Fruit20
11. Fruit100
12. Pear
Examples of generated documentation:
https://docs.charr.xyz/before-doc/test_sorting/https://docs.charr.xyz/after-doc/test_sorting/
Screenshots of generated documentation:
Before: http://imgur.com/Ktb10ti
After: http://imgur.com/CZJjqIN
rustdoc: Only include a stability span if needed.
This patch gets rid of the empty stability boxes in docs by only including the span that creates it when the item actually has a stability class.
Here are images of the issue on `std::process::Output`:
Before:
<img width="340" alt="before" src="ff88d1b2-f010-11e6-90d6-bf3d10e2fffa.png">
After:
<img width="333" alt="after" src="06bfe7cc-f011-11e6-9892-f0ea2cc6ec90.png">
This is my first non-trivial patch to Rust, so I'm sure some of my approach is not idiomatic. Let me know how you'd like me to adjust!
rustdoc: Show attributes on all item types
Currently attributes are only shown for structs, unions and enums but
they should be shown for all items. For example it is useful to know if a
function is `#[no_mangle]`.
Currently attributes are only shown for structs, unions and enums but
they should be shown for all items. For example it is useful to know if a
function is `#[no_mangle]`.
* Don't disambiguate if there are multiple impls for the same type.
* Disambiguate for impls of &Foo and &mut Foo.
* Don't try to disambiguate generic types.
rustdoc: escape the deprecated and unstable reason text
Fix#38220.
Instead of the [current output](https://doc.rust-lang.org/std/boxed/trait.FnBox.html):
<img width="967" alt="incorrect unescaped unstable reason in docs" src="73121d42-bd2f-11e6-8076-8a5127dbc010.png">
display:
<img width="979" alt="escaped unstable reason in docs" src="52eb0f88-bd2f-11e6-9088-58bdc7d92328.png">
