Better listing of dependencies in 'cargo docs' sidebar output

[dbr]

Describe the problem you are trying to solve
In short: in the generated HTML docs, the sidebar list of dependencies isn't very useful in any project with many (tens or hundreds) of dependencies.

Longer:

In the cargo docs output for my application, there is a huge list of crates listed in the sidebar (around 200). Very few of these are interesting to me - a huge majority are indirect dependencies potentially 10+ levels deep, but they are presented in a flat listing.

It's good these are documented, but listing them in the sidebar so prominently doesn't seem helpful to me, as almost all of the time I either want to:

1. look at the documentation for my application code
2. look at one of my main direct dependencies (i.e one of the packages I list in Cargo.toml)

When you first open the docs (e.g cargo docs --open) it lists all my apps modules and so on. This is good.

However if I want to find the docs for, say, serde_json, I have to scroll down the very long list (I could ctrl+f search, but at that point I might as well use the doc's nice search feature)

Then, once you have clicked on a dependency, it's hard to directly navigate back to my application's docs (have to find myapp in the sidebar, or, search)

Describe the solution you'd like
I think this has a two parts - I don't have strong opinions on the exact design etc, but the functionality I would find very useful are:

1. Always having a "single click" link back to the "main crate" (the one cargo docs was run for) in some way

   Say if I run cargo docs --open for myapp, I would expect that there would be a link at the top of the sidebar which links back to ./target/doc/myapp/index.html.

   Currently, I would expect clicking the Rust logo at the top would go back here, but it goes to the index of the currently-clicked package docs

2. Prioritizing the packages in the sidebar somehow.

   Some ideas for this might be:

   • Display them in a hierarchy similar to cargo tree. Might not work too well in the narrow side bar
   • Reorder them so the "direct dependencies" are listed first, followed by all the other dependencies (or a toggle to display "all dependencies" or "only direct dependencies")
   • Display the top-level dependencies in the side bar, then display the "dependencies of this package" in a separate UI element somehow (e.g if I use reqwest then only display that in sidebar - then if I click on reqwest, then display the dependencies of that like hyper etc)
   • A way to specify the "interesting" dependencies in Cargo.toml - ones which would appear more prominantly in the sidebar. Kind of like a "favourites"

Notes

This idea only relates to the UI presentation of the sidebar, it wouldn't reduce the amount of documentation generated, and should be doable in a way which makes the big list of dependencies still available as it is surely valuable in some circumstances

Of the existing options there is a few which sort of help with this problem, not don't do what I'm hoping for:

cargo doc --no-deps is too drastic, completely removes the dependencies.

cargo doc --exclude could kind of solve this (exclude everything except my top-level deps), but having the indirect dependencies available is still useful (particularly via search or links from return types etc etc), and this is very cumbersome to maintain

[ehuss]

Transferred to rust-lang/rust, as this issue is about rustdoc and its issues are tracked here.

[jyn514]

Currently, I would expect clicking the Rust logo at the top would go back here, but it goes to the index of the currently-clicked package docs

I agree we should fix this. If you want to go to the root of the current crate, you can always click on the crate name on the item you're looking at.

Prioritizing the packages in the sidebar somehow.

I'm not opposed to this, but it's the sort of change that only happens if someone volunteers to put in the time. I'm happy to help mentor if you want to work on it.

[ThePuzzlemaker]

This sounds like a pretty interesting project to work on. It may take a while for me to do this but luckily this doesn't seem like an issue that is very critical, to be honest (Though I may split it into two parts: fixing that first issue about the rust logo, and possibly prioritizing packages in the sidebar). Wish me luck!
@rustbot claim

[ThePuzzlemaker]

As for sidebar reordering, I'm thinking something like this could be helpful:

1. Top-Level Dependencies (probably including workspace deps)
2. Local Dependencies (path deps and/or maybe workspace deps)
3. Direct Dependencies
4. Indirect Dependencies

(maybe in their own sections? idk)

[real-felix]

I'm not opposed to this, but it's the sort of change that only happens if someone volunteers to put in the time. I'm happy to help mentor if you want to work on it.

I need that feature, so I'm willing to help (depending on the time needed: how long would it take?).

At least, I think that the workspace crates should be separated from the dependencies to emphasize the content of the project.

[jyn514]

depending on the time needed: how long would it take?

I don't know; most of rustdoc is frankly not very good code, it's very interconnected and small changes in one area can have unexpected side effects. I'd suggest writing your change then seeing if the tests fail.

I no longer have time to mentor this, but @GuillaumeGomez or @jsha may.

[GuillaumeGomez]

Sorry, missed this issue. There is a work in progress already in #84834. Once this one is merged, you can try changing what you have in mind?