Documentation failed to build in docs.rs

[dtolnay]

Will need to dig into what happened here. For now our documentation is serving a 404.

https://docs.rs/crate/proc-macro2/0.4.21/builds/126085

$ rustc --version
rustc 1.31.0-nightly (78ff609d7 2018-10-19)
$ cratesfyi --version
cratesfyi 0.6.0 (c695234 2018-11-02)
$ cratesfyi ...
    Updating crates.io index
 Downloading crates ...
  Downloaded proc-macro2 v0.4.21
   Compiling proc-macro2 v0.4.21
       Fresh unicode-xid v0.1.0
     Running `rustc --crate-name build_script_build /home/cratesfyi/.cargo/registry/src/github.com-1ecc6299db9ec823/proc-macro2-0.4.21/build.rs --color never --crate-type bin --emit=dep-info,link -C debuginfo=2 --cfg 'feature="default"' --cfg 'feature="proc-macro"' -C metadata=167aa8b4d7bae7c9 -C extra-filename=-167aa8b4d7bae7c9 --out-dir /home/cratesfyi/cratesfyi/debug/build/proc-macro2-167aa8b4d7bae7c9 -L dependency=/home/cratesfyi/cratesfyi/debug/deps --cap-lints allow`
     Running `/home/cratesfyi/cratesfyi/debug/build/proc-macro2-167aa8b4d7bae7c9/build-script-build`
 Documenting proc-macro2 v0.4.21
     Running `rustdoc --crate-name proc_macro2 /home/cratesfyi/.cargo/registry/src/github.com-1ecc6299db9ec823/proc-macro2-0.4.21/src/lib.rs --cap-lints allow --color never -o /home/cratesfyi/cratesfyi/doc --cfg 'feature="default"' --cfg 'feature="proc-macro"' -Z unstable-options --resource-suffix -20181019-1.31.0-nightly-78ff609d7 --extern-html-root-url 'unicode_xid=https://docs.rs/unicode-xid/0.1.0' --cfg procmacro2_semver_exempt -L dependency=/home/cratesfyi/cratesfyi/debug/deps --extern unicode_xid=/home/cratesfyi/cratesfyi/debug/deps/libunicode_xid-264701959ae3940e.rmeta --cfg u128 --cfg use_proc_macro --cfg wrap_proc_macro`
error[E0412]: cannot find type `SourceFile` in module `imp`
   --> /home/cratesfyi/.cargo/registry/src/github.com-1ecc6299db9ec823/proc-macro2-0.4.21/src/lib.rs:223:28
    |
223 | pub struct SourceFile(imp::SourceFile);
    |                            ^^^^^^^^^^ not found in `imp`
help: possible candidates are found in other modules, you can import them into scope
    |
56  | use SourceFile;
    |
56  | use proc_macro::SourceFile;
    |
56  | use stable::SourceFile;
    |

error: Compilation failed, aborting rustdoc

thread 'main' panicked at 'ProcessError { desc: "process didn\'t exit successfully: `rustdoc --crate-name proc_macro2 /home/cratesfyi/.cargo/registry/src/github.com-1ecc6299db9ec823/proc-macro2-0.4.21/src/lib.rs --cap-lints allow --color never -o /home/cratesfyi/cratesfyi/doc --cfg \'feature=\"default\"\' --cfg \'feature=\"proc-macro\"\' -Z unstable-options --resource-suffix -20181019-1.31.0-nightly-78ff609d7 --extern-html-root-url \'unicode_xid=https://docs.rs/unicode-xid/0.1.0\' --cfg procmacro2_semver_exempt -L dependency=/home/cratesfyi/cratesfyi/debug/deps --extern unicode_xid=/home/cratesfyi/cratesfyi/debug/deps/libunicode_xid-264701959ae3940e.rmeta --cfg u128 --cfg use_proc_macro --cfg wrap_proc_macro` (exit code: 1)", exit: Some(ExitStatus(ExitStatus(256))), output: None }

Could not document `proc-macro2`.', src/bin/cratesfyi.rs:142:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.

[dtolnay]

Documenting that release with that compiler does work locally...

$ git checkout 0.4.21
$ RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo +nightly-2018-10-20 doc

[dtolnay]

From tracing through the feature flags, this failure means that the build was configured as follows:

• with cfg(procmacro2_semver_exempt) because lib.rs:223 is being compiled;
• with cfg(wrap_proc_macro) because cfg(not(wrap_proc_macro)) unconditionally defines imp::SourceFile in stable.rs;
• without cfg(super_unstable) because unstable.rs is not defining SourceFile.

Relevant configuration on our end:

https://github.com/alexcrichton/proc-macro2/blob/3f8382d1bb42f0121707660b9b7f0628a371c840/Cargo.toml#L21-L22

https://github.com/alexcrichton/proc-macro2/blob/3f8382d1bb42f0121707660b9b7f0628a371c840/build.rs#L25-L31

---

From this I conclude that --cfg procmacro2_semver_exempt is not being passed when building the build script. There may be a different field in [package.metadata.docs.rs] that also needs to be set.

[dtolnay]

The docs are fine for 0.4.20 but failed to build for 0.4.21. #144 did touch build.rs in that range but I don't see anything in that change that would break this way.

Meanwhile there have been lots of commits to https://github.com/rust-lang-nursery/docs.rs between our two releases. rust-lang/docs.rs@32102ce...c695234

Mentioning @QuietMisdreavus in case anything rings a bell.

[QuietMisdreavus]

Working backwards from the command-lines given by Cargo in the log...

(when building the build script)
$ rustc ... --cfg 'feature="default"' --cfg 'feature="proc-macro"'

(when documenting the crate)
$ rustdoc ... --cfg 'feature="default"' --cfg 'feature="proc-macro"' ... --cfg procmacro2_semver_exempt ... --cfg u128 --cfg use_proc_macro --cfg wrap_proc_macro

But in the build log for 0.4.20...

(when building the build script)
$ rustc ... --cfg 'feature="proc-macro"' --cfg 'feature="default"'

(when documenting the crate)
$ rustdoc ... --cfg 'feature="proc-macro"' --cfg 'feature="default"' ... --cfg procmacro2_semver_exempt ... --cfg use_proc_macro

It looks like 0.4.21 is getting more cfg flags. I don't think the rustdoc-args configuration was ever given to the build script. It's analogous to setting $RUSTDOCFLAGS or using cargo rustdoc.

[dtolnay]

279519f seems to fix it. I released 0.4.22 and filed rust-lang/docs.rs#262 to follow up in docs.rs.

[QuietMisdreavus]

I think i found the major difference:

https://github.com/alexcrichton/proc-macro2/blob/553aaa900be64c2b36ec34b90c54c4b493500f79/build.rs#L24-L31

The rustc used by docs.rs until recently had the version string 1.28.0-dev, which caused the wrap_proc_macro to not get set. Now that the compiler is new enough, it goes into that block to set cfg(wrap_proc_macro), which leaves in the hole you've now discovered.

[dtolnay]

Right you are! I missed that the previous version was building with 1.28.0-dev. 👏 Thanks and apologies for dragging you into this.