Description
TL;DR: cargo publish should default to also running cargo doc and publishing the output online.
Having a crate’s documentation like http://doc.rust-lang.org/std/ available online is immensely valuable. Not only when using it, but also when deciding whether to use it (and so before cargo doc can be run locally).
Therefore, every crate on crates.io would ideally have its documentation online. For that to happen, it should be as easy as possible, with minimal effort from the developer.
The defaults should just work. cargo publish already involves building and testing crates, so documentation can be built at the same time. Even without any doc-comment, the rustdoc output can be useful. When the source package is uploaded to crates.io, the built documentation can be uploaded at the same time and be made available at https://example.net/[package-name]/ or https://example.net/[package-name]/[package-version]/, where example.net is a domain name managed together with crates.io. This URL should be linked from https://crates.io/crates/[package-name]
Although rustdoc is the default, if a project decides not to use rustdoc it should still be able to publish its documentation through this mechanism.
This effectively means providing free hosting of static files, which should be watched for abuse, but there is precedent: the Python Package Index does something similar with https://pythonhosted.org/. They have an HTTP API where one can upload a ZIP file, which the server exctracts to replace any previous content. Integration with Sphinx and distutils so that python setup.py upload_docs builds the documentation with Sphinx, zips it, and uploads it in one command.
Another case is Read The Docs, which pulls repositories and builds Sphinx documentation on its servers and can be trigerred on every commit by a GitHub hook. This is more risky as it involves running arbitrary code on the server.
If Cargo makes publishing/releasing a new version very easy, hopefully it can establish a convention in the Rust ecosystem of releasing often, so that updating the online docs for every commit (as opposed to releases) is not as necessary.
rust-lang/cargo#1016 would work well together with this. If rust-lang/cargo#1017 happens, it should be enabled for this.
Unresolved question: should the docs be made available for every version (at different URLs), or only the latest? If the former, should there be an unversioned URL for a default version? Is it a duplicate or a redirect? What navigation exists between versions? Read The Docs has a fixed-position overlay for this.