Skip to content

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

Closed
@SimonSapin

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions