Skip to content

Add a toc to each std lib generated pages #28056

@mdinger

Description

@mdinger
Contributor

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:

toc

Activity

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
on Aug 28, 2015
added
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
on Nov 15, 2016
steveklabnik

steveklabnik commented on Nov 15, 2016

@steveklabnik
Member

Triage: no change.

added
T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
and removed on May 18, 2017
steveklabnik

steveklabnik commented on Sep 24, 2018

@steveklabnik
Member

Triage: no changes. @rust-lang/rustdoc is this a feature we're interested in pursuing?

GuillaumeGomez

GuillaumeGomez commented on Sep 24, 2018

@GuillaumeGomez
Member

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

jyn514 commented on Jul 2, 2021

@jyn514
Member

Duplicate of #14475

added a commit that references this issue on Sep 5, 2024
f0de876
added a commit that references this issue on Sep 5, 2024
e1da72c
added a commit that references this issue on Sep 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    C-enhancementCategory: An issue proposing an enhancement or a PR with one.T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @steveklabnik@sfackler@GuillaumeGomez@mdinger@jyn514

        Issue actions

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