cargo doc should create a target/doc/index.html "home page"

[SimonSapin]

If I run cargo doc with a foo crate, target/doc/foo/index.html will have the documentation for that crate. This page requires files in the parent directory common to all crates, like target/doc/main.css. So if I publish the contents of target/doc at https://example.net/, https://example.net/foo/ will be the documentation of crate foo. (Assuming the http server is configured, like most are, to respond to requests for a directory with the contents of index.html.)

However, since target/doc/index.html is not created, browsing to https://example.net/ will give either a file listing or an error message. cargo doc or rustdoc should create it and have something there.

At a minimum, it could be a redirect to foo/index.html for the "main" crate. (Maybe the one in the Cargo.toml that cargo doc is run with?) See for example doc.servo.org/index.html.

More usefully, it could be the contents of the file pointed by the package.readme manifest key (which by the way could default to README.md when the file exists, it’s unclear if it does already), rendered as Markdown, with the same stylesheet as other documentation pages, with the crate index in the side bar and the search bar in the header.

There should be a way to disable or override this, for projects that already have something like http://doc.rust-lang.org/index.html to put there.

[steveklabnik]

👍

[SimonSapin]

If target/doc/index.html has useful content, perhaps some other pages (crate doc indexes? all pages?) should link back to it somehow.

[alexcrichton]

I'm going to close this in favor of #739 as given my current thoughts this would basically just be doc/index.md

[SimonSapin]

Sounds good.