Feature idea: cargo doc generating an index.html for workspaces, with a list of the workspace's crates

[Ekleog]

Describe the problem you are trying to solve

I have a workspace with a list of crates. cargo doc does not generate a target/doc/index.html, and cargo doc --open just opens the crate of the workspace.

Describe the solution you'd like

Ideally, cargo doc would also generate a target/doc/index.html that contains eg. an index of all the crates that are (directly) in the workspace. This would make everything more discoverable, and would allow to just point to [built-docs]/index.html without having to write one by hand that wouldn't have the expected look-and-feel :)

[ehuss]

Rustdoc has a nightly/experimental flag which already does this to some degree: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#--index-page-provide-a-top-level-landing-page-for-docs

RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc

--open isn't aware of that option, though.

[Ekleog]

Oh, this is cool :) I was looking for cargo flags, as I assumed that rustdoc worked crate-by-crate — looks like there's something I was missing in the interactions between the two.

Do you know if there are any plans on making this feature available directly from cargo doc, even if it is nightly-only?

[ehuss]

No plans I am aware of. I'm not even sure why the flag was added. If you want to ask the rustdoc team, rustdoc issues live in the rust repo or there is a #rustdoc channel on discord.

[Ekleog]

Hmm… but… adding a flag to cargo doc is a project for cargo, not for rustdoc… is it not? Maybe I misunderstand some of the ownership, then :)

[ehuss]

The --enable-index-page flag in rustdoc is currently unstable. Before changing Cargo, we would need to figure out what the story is for that flag, and if it there is any desire or plan to stabilize it. There are alternate solutions, like rustdoc could just always generate an index page by default, and we could just get rid of the flag altogether.

So it would take some coordination with the rustdoc maintainers to figure out the story here. What the motivation is, the alternatives, etc.

[Ekleog]

Oh, I understand now :) thank you for your explanation! I've just opened rust-lang/rust#73185 to ask these questions, redirecting people to maybe answer here so I don't end up being an unnecessary middleman between people who actually know what they're talking about :)