-
Notifications
You must be signed in to change notification settings - Fork 13.6k
Description
Long pages such as in regex have many examples but it's difficult to know at a glance what the documentation contains without scanning the entire document. Having a table of contents would help a lot with this.
Here is a list of links to different TOC styles from various places for ways it could be done:
- Python 2.7 has one in the sidebar. Stays with you as you scroll.
- Python 3.5 seems to be slightly cleaner but similar. Doesn't stay with you.
- mozilla javascript docs: is nicely in the sidebar. Follows you down the page (requires the window to be wide enough).
- wikipedia: in the middle of the page. Doesn't scroll with you.
- gitbook: stays with you. provides scrolling.
- perl: looks like it's formatted like a man page.
I looked for some more but didn't find other good examples.
Of these, I like the mozilla, python 2, and gitbook TOCs best with the mozilla probably the best among them (probably because it's small and clean). However, I think the gitbook style is probably the most appropriate fit to the std libs style.
I've also provided a mockups of what a TOC could look like in that style which is similar to a different thread. Clearly, something would need to be done with the current sidebar to use this format.
Mockup:
Activity
steveklabnik commentedon Nov 15, 2016
Triage: no change.
steveklabnik commentedon Sep 24, 2018
Triage: no changes. @rust-lang/rustdoc is this a feature we're interested in pursuing?
GuillaumeGomez commentedon Sep 24, 2018
This would be very nice to have but I currently don't know how we could do it... The problem is that our pages are already very loaded and that'd add even more content to be able to go through content. Also, not sure the information would be more accessible like this. It'd force to have a very clean documentation through meaningful titles.
jyn514 commentedon Jul 2, 2021
Duplicate of #14475
Rollup merge of rust-lang#120736 - notriddle:notriddle/toc, r=t-rustdoc
Rollup merge of rust-lang#120736 - notriddle:notriddle/toc, r=t-rustdoc
Unrolled build for rust-lang#120736
Rollup merge of #120736 - notriddle:notriddle/toc, r=t-rustdoc