Rust: Rustdoc could (have an option to) create a top-level index page

[huonw]

Currently rustdoc creates doc/foo/index.html doc/bar/index.html (etc.) for crates foo, bar, along with doc/searchIndex.js. We could provide a way to create a human readable doc/index.html summarising all the crates in a folder (like how the search index works).

This could even take a markdown/html file as input to provide a longer description (theoretically this may allow Rust's current index.md top-level file to be properly integrated into the crate docs, although this may not be desirable, which is why this functionality should be optional).

[steveklabnik]

:+1:

[thehydroimpulse]

/cc me

[huonw]

This could also some try to integrate with any standalone markdown files, e.g. projects might have a tutorial or some specific feature guides just like the main repo.

[steveklabnik]

Triage: no change. We have been discussing a Cargo feature which would let you build standalone files with Rustdoc, so I'm not sure if maybe that isn't a better approach anyway. Maybe.

[nixpulvis]

:+1:

[nixpulvis]

I'm thinking this could be solved in addition to a way for cargo to build arbitrary docs. For example.

<project>/
    doc/
        index.<ext>
        dir/...
        <filename>.<ext>
    src/
    ...

Here the index.<ext> will be the index page, and other files are served according to the file directory structure.

[frewsxcv]

We have been discussing a Cargo feature which would let you build standalone files with Rustdoc

Link to the associated issue: https://github.com/rust-lang/cargo/issues/739

[steveklabnik]

Triage: no change. @rust-lang/rustdoc do we ever plan on implementing this?

[GuillaumeGomez]

That is actually a good idea! It's a shame I never came across it earlier. Adding it.

[QuietMisdreavus]

Update: This was implemented in https://github.com/rust-lang/rust/pull/54543, which is currently being tested by bors.

[GuillaumeGomez]

And it has been merged so I'm closing it.