Add a toc to each std lib generated pages · Issue #28056 · rust-lang/rust (original) (raw)

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: