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 —expect-doc to 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 cargo publish.
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.