A crate may fail in generating documentations on https://docs.rs. When it happens, the crate has been published successfully and the author has no chance to correct mistakes. Doing
cargo doc before
cargo publish does not always helps to prevent it.
How about adding a new option
cargo publish? If doc generating fails, the publishing will also fail, with error messages indicating the detailed reason, displayed in terminal.
It should be possible to write program which will run
cargo package on your crate, locally build docs for the generated tarball using rustwide and then if that succeeds run
How docs.rs builds the docs isn't entirely stable, so it's not possible to have
cargo know exactly what will be run once it's published, it also involves a 9GB docker image if you want to verify with the exact native dependencies so not really something you want running locally all the time.
You'd get 95% of the way there just by setting up a CI job building the docs using the nightly compiler, ensuring that it uses the same flags you might have configured in
[package.metadata.docs.rs], and maybe setting
DOCS_RS=1 in case your or your dependencies build scripts use that to change behavior. The next major thing that trips up some crates is the fact that the sandbox makes the source directory read-only, using
rustwide or just something like
bubblewrap would let you simulate that part of it.
What are some examples of errors that happen on docs.rs that would be caught at the publish stage?
My only knowledge of errors is around things like missing C libraries, which I'm not sure would get caught.