search

rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
97.01k stars 12.54k forks source link

rustdoc: Allow customizing the crate list sidebar. #16328

Open SimonSapin opened 10 years ago

SimonSapin commented 10 years ago

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?

thehydroimpulse commented 10 years ago

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.

steveklabnik commented 9 years ago

Triage: no change.

steveklabnik commented 7 years ago

Triage: still no changes.

steveklabnik commented 6 years ago

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

GuillaumeGomez commented 6 years ago

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

SimonSapin commented 5 years ago

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?

QuietMisdreavus commented 5 years ago

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.

robinmoussu commented 4 years ago

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