Should crates.io documentation point to docs.rs by default?


#1

Currently, if one leaves the “documentation” field of a crate’s Cargo.toml file empty, the crates.io project page will feature no documentation. Because of this, many crates have either no documentation at all, or self-hosted documentation (which is cumbersome to maintain, and may thus not be up to date).

While investigating a better solution for my project, I have discovered that there is this wonderful docs.rs service which automatically builds and hosts the documentation of every cargo crate. For me, it was a no-brainer: I HAD to use this.

With this in mind, I’m wondering: shouldn’t crates.io point to docs.rs by default if no project-specific documentation link has been sent? The answer is not obvious to me, because it would have broader political and technical implications: the docs.rs servers would be getting a lot more traffic which nobody’s paying for, the crates.io and docs.rs projects would become de facto linked to one another…

So I’m asking for your comments on this idea: what do you think about it? Does it sound right to you? In particular, I would very much like people from crates.io and docs.rs to contribute to the discussion and express the view of each project on this.


#2

As a Docs.rs user myself, +1 to this.

Normally when you publish a crate, you also have to build the documentation, possibly for multiple platforms and build configurations, upload it somewhere, make sure your links are up-to-date, etc. etc. And mistakes can happen - I’ve had to yank crates in the past because of one missed link that pointed to outdated docs. All of this takes time that you could have spent on coding instead.

Docs.rs handles all of this for you, so you only have to remember to update the documentation field in Cargo.toml. By having crates.io point to it by default, you wouldn’t even have to worry about that; you could just publish a new version and within minutes have fully up-to-date documentation for a variety of platforms. Imagine how much more code we could write if everybody did this!

Actually, I’ll go one step further - I think Docs.rs should become an official Rust project. IMO the service is too useful to not consider using, and it’d benefit enormously from the added visibility and scrutiny that comes with being an official project.


#3

docs.rs is a great service, and it would be useful to have a link for every crate, but please don’t make it in a way that would discourage or replace proper human-written documentation.

Rustdoc output is an unordered function reference organized mostly alphabetically, and not by logical structure of the project. It’s useful if you want to look up a specific function or a type, but it exposes everything at once, without any good place to begin, without any order to read through it. As such, it’s unsuitable for learning how to use a crate and understanding the big picture of crate’s design.

So I’d vote to add another “Reference” link, and leave Documentation as-is, to encourage adding proper manuals and tutorials as well.


#4

I think docs.rs should be merged with crates.io.
They really belong together.


#5

I think the solution to this is not to avoid docs.rs (which mostly runs cargo doc and provides hosting, and is fairly agnostic regarding what is hosted) but to extend cargo doc and/or rustdoc to enable prose-first documentation.


#6

Yes! Crates.io wants this, and I am available to help anyone who wants to implement it! Here’s what needs to be done, feel free to leave comments on that issue if you have questions!!


#7

Great to hear that it’s already on your radar! Personally, I don’t think I would be sufficiently [good at|interested in] web-dev to do this right, but I really hope you’ll find someone suited for this task :slight_smile: