rustdoc: Allow customizing the crate list sidebar.

f684848
Opened by Simon Sapin at 2024-11-07 21:51:23

http://doc.servo.org/servo/index.html is the rustdoc documentation for Servo’s own crates, those of all dependencies (submodules), and Rust’s (for the version used by Servo, which is usually a few weeks behind Rust master.)

Currently, this is a total of 69 crates that are listed in alphabetical order. Instead, I would like the sidebar to have three sub-sections (Servo, submodules, and Rust) each listing the corresponding crates. The sidebar is generated by a copy of src/librustdoc/html/static/main.js, and therefore is not easy to customize.

Could rustdoc help with this? Perhaps, rather than adding a feature for exactly what Servo wants, enable arbitrary behavior by providing a hook for overriding the bit of JS that generates the sidebar?

  1. I'm thinking the best way would be a configuration file of some sort. Like a doc.json which could customize these things without passing a ton of flags to rustdoc.

    This could also be a solution to adding other stylesheets to customize the styles and such.

    Daniel Fagnan at 2014-08-27 19:31:52

  2. Triage: no change.

    Steve Klabnik at 2015-09-03 15:02:36

  3. Triage: still no changes.

    Steve Klabnik at 2016-11-15 20:46:52

  4. Triage: still no changes, no substantial comments in over four years. @rust-lang/rustdoc are we interested in pursuing this feature?

    Steve Klabnik at 2018-09-24 16:04:51

  5. Maybe? More details on what's wanted would be appreciated here because I have difficulties to get the whole picture.

    Guillaume Gomez at 2018-09-24 19:18:50

  6. Well, you can visit https://doc.servo.org/servo/index.html and see that the sidebar as it is today is not particularly helpful. Since this issue was opened, the count went from 69 to 326 crates listed.

    Maybe only listing same-workspace only would be a good start?

    Simon Sapin at 2018-09-25 06:48:09

  7. Rustdoc doesn't have a concept of workspaces; only cargo does. If cargo gains the ability to only document items in the workspace, would that help any? (I'm not sure if such an ability already exists, to be honest...)

    Currently, the crate list is dynamically loaded from the search index. If we want to provide a way to filter the crates list, it will affect the entire doc bundle, not just one crate's docs. Any change to the crates listing needs to confront that, whether by adding features to Cargo to only run docs for select crates, or for rustdoc to have some kind of listing that is on each file in the same crate that can be used to filter that list out.

    QuietMisdreavus at 2018-11-02 16:59:29

  8. Personally I would like to have only the items of the current workspace in the side-bar (without any other changes).

    Robin Moussu at 2020-08-24 12:25:56

  9. triage: still no change

    lolbinarycat at 2024-11-07 21:51:23