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?

[jyn514]

@GuillaumeGomez I'm not sure how that PR is related? It affects where the sidebar is displayed but not the contents.

[GuillaumeGomez]

It heavily affects the sidebar content. ;)

[real-felix]

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.

Eheh, I have a bad feeling about this 😅

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?

You can ping me when I can implement this change.

[GuillaumeGomez]

Subscribe to the PR then, I'm about to send an update there. :)

[jsha]

@dbr for your use case, do you need the less-important docs to still be generated (but hidden)? Or would it be acceptable for them to not be generated at all?

Currently cargo doc has these two flags:

        --exclude <SPEC>...          Exclude packages from the build
        --no-deps                    Don't build documentation for dependencies

Perhaps a good solution for your use case would be a flag like --include <crates>, which would generate docs only for the dependencies explicitly listed.

[jsha]

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

I looked a little at fixing this (I agree, this should work!), and ran into some issues. As I understand it, when you run cargo doc, rustdoc gets run multiple times, once for each dependency. With the current rustdoc flags, there's no particular notion of one invocation being for the "main" crate of a cargo doc invocation. Perhaps we have to add a flag?

Also, rustdoc has these flags:

        --index-page PATH
                        Markdown file to be used as index page
        --enable-index-page 
                        To enable generation of the index page

When the index page is present, clicking the logo should take you to the index page, rather than the "main" crate. I'm not sure if cargo doc can pass these flags, so maybe it winds up not mattering.

One somewhat hacky approach would be: The logo points to {root}/index.html instead of any specific crate. When cargo doc is done invoking rustdoc all those times, if there is not currently a {root}/index.html, it creates one with a JS redirect to the main crate's page.

[jyn514]

I'm not sure if cargo doc can pass these flags, so maybe it winds up not mattering.

It can if you use RUSTFLAGS. You can't passes flags to rustdoc with cargo doc -- --some-flag though.

[TomFryersMidsummer]

As a workaround, it's quite straightforward to automate purging non-workspace crates from the documentation:

python -c 'import tomllib; from pathlib import Path; m = [c.replace("-", "_") for c in tomllib.load(Path("Cargo.toml").open("rb"))["workspace"]["members"]]; Path("target/doc/crates.js").write_text(f"window.ALL_CRATES = {m};")'

Makefile:

removemembers = python -c \
'import tomllib ;\
from pathlib import Path ;\
m = [ \
	c.replace("-", "_") \
	for c in tomllib.load(Path("Cargo.toml").open("rb"))["workspace"]["members"] \
] ;\
Path("target/doc/crates.js").write_text(f"window.ALL_CRATES = {m};")'

.PHONY: doc
doc:
	cargo doc --lib --bins
	$(call removemembers)