Use --config build.rustdocflags instead of cargo rustdoc -- <flags>

[willcrichton]

For the --scrape-examples feature, it's important that rustdoc flags like --static-root-path be passed to all rustdoc invocations. This way, sources generated for reverse dependencies have the correct root path.

To fix this issue, this PR changes the call to cargo rustdoc to move flags that were previously passed via -- <flags> to RUSTDOCFLAGS=<flags>.

[jyn514]

Passing this to all invocations of rustdoc is fine, but using RUSTDOCFLAGS is not the right approach, because it mangles whitespace. Please use -Zconfig, like rustcflags uses. This should also have the benefit that you don't need to change the API, just the implementation.

[willcrichton]

Ohh I understand. @jyn514 does the latest commit look like what you expect then?

[jyn514]

This looks great, can you just remove the "this will always contain --" comment? https://github.com/rust-lang/docs.rs/pull/1543/files#diff-8d09c60bb352ed9bc4b67f0b237ac3255c69a598110de8358647452efee1d4e3R229

[willcrichton]

Done.

[nagisa]

I believe this has resulted in all dependencies receiving the flags specified in package.metadata.docs.rs.rustc-args.

Most notably a commonly used --cfg docsrs does not necessarily will allow a dependency to compile (but the code remains valid enough to document). And cargo rustdoc compiles the dependencies for some reason.

[willcrichton]

Perhaps the solution is to carve off a whitelist of flags like --static-root-path that are passed in via build.rustdocflags and pass the remaining flags as they were before?

[nagisa]

…Actually, nevermind. I missed the distinction between build.rustdocflags and build.rustflags. Builds with build.rustdocflags still work fine!