Better integration with docs.rs

[tliron]

As it stands right now, cargo publish can succeed while generating documentation on docs.rs will fail.

The reason is clear enough (these are separate services), but the experience of publishing crates can be painful. Docs.rs is finicky for various reasons and little things can cause the documentation build to fail. It's enough to take a look at many popular crates on docs.rs to see that many smart and experienced developers stumble with this aspect.

The recourse is awkward. Code changes need to be made, which necessitate bumping the version of the crate and re-publishing. It's not the end of the world, but it makes version progression arbitrarily tied to these snafus, which can end up confusing users who might not understand why a version has been bumped. The "bad" version can be yanked, but not all devs do this, and in any case that also leaves a confusing impression on users.

I can think of two approaches to solving this:

The first is server-side. Crates.io could, potentially, avoid publishing the crate until docs.rs tells it that documentation has been built successfully. This would mean that both crates.io and docs.rs would need an internal "staging area" and only move the crate to the public when both sites are OK with it. This would, I believe, give the best experience for users, but it's obviously not so trivial to implement. There could also be a flag for cargo publish to disable this behavior for super-confident users. :)

The second solution would be client-side. The cargo rustdoc command can be set to run before uploading to crates.io. I'm less enthused with this solution, because invariably the client-side environment would be different from what docs.rs actually does with its docker images and all. Mismatches would surely still happen. But if the server-side solution is really too hard to achieve, this would be better than nothing, and it could be a stop-gap solution until the server-side solution could be made available.

[syphar]

I'm not sure if I would like the staging are idea, enforced.

Depending on the amount of releases / built-times etc it can take multiple days or even a week until your build is finished.

Secondly I could totally imagine crate authors that rather want a fast release, where docs come later.

I believe the best approach is your own CI suite.

You can easily add something like cargo docs-rs to it, which will already catch many of the potential issues.

For libraries with c-dependencies I could imagine an extension where you can run your build inside our docker container. This could cover the rest. Taking contributions :)

[tliron]

I suggested staging could possibly be enabled/disabled with a flag. I don't personally care what the default would be.