#[cfg(doc)] does not work in Cargo.toml

[arctic-hen7]

Hey! I'm working on a library that uses two custom RUSTFLAGS to control what it provides for different environments, and those two flags are mutually exclusive. However, I wanted to make sure items from both were available in the documentation produced by cargo doc, so I followed these instructions and used #[cfg(doc)] for this. That works excellently, except the dependencies of the crate are also controlled by these custom flags (e.g. [target.'cfg(engine)'.dependencies]), so I expected to be able to write something like this:

[target.'cfg(any(client, doc))'.dependencies]

However, this doesn't seem to work at all, because I still get all the usual unresolved import errors. Changing this to use another custom flag clientdoc, rather than the internal doc, and then running

RUSTFLAGS="--cfg=engine --cfg=clientdoc" cargo doc

works perfectly. (Although one of these custom flags is involved with importing traditionally Wasm-specific crates, I am almost certain that this is not the problem.)

I expected that #[cfg(doc)] would, like any custom RUSTFLAGS I provide, be applied to Cargo.toml as well as the actual code.

Instead, this does not seem to occur, and another custom flag has to be used, which isn't ideal.

Meta

rustc --version --verbose:

rustc 1.68.0-nightly (92c1937a9 2022-12-27)
binary: rustc
commit-hash: 92c1937a90e5b6f20fa6e87016d6869da363972e
commit-date: 2022-12-27
host: x86_64-unknown-linux-gnu
release: 1.68.0-nightly
LLVM version: 15.0.6

Backtrace

<many more errors of the same kind>
error[E0432]: unresolved import `web_sys`
  --> packages/perseus/src/reactor/initial_load.rs:19:5
   |
19 | use web_sys::Element;
   |     ^^^^^^^ use of undeclared crate or module `web_sys`

error[E0432]: unresolved import `wasm_bindgen`
   --> packages/perseus/src/reactor/initial_load.rs:256:13
    |
256 |         use wasm_bindgen::JsCast;
    |             ^^^^^^^^^^^^ use of undeclared crate or module `wasm_bindgen`

error[E0433]: failed to resolve: use of undeclared crate or module `web_sys`
  --> packages/perseus/src/utils/render.rs:25:13
   |
25 |     parent: web_sys::Element,
   |             ^^^^^^^ use of undeclared crate or module `web_sys`

error: Compilation failed, aborting rustdoc

Some errors have detailed explanations: E0432, E0433.
For more information about an error, try `rustc --explain E0432`.
error: could not document `perseus`

[weihanglo]

IIRC, Cargo doesn't pass --cfg doc to rustdoc invocations. Instead, it lets rustdoc doing its own job. As a result, when resolving dependencies, Cargo doesn't know the existence of --cfg doc, so it cannot resolve that cfg expression to get the desired dependencies. Similarly, the lack of support of cfg(features="X") also falls in that category ¹.

Here are some related you might be interested in:

• Discuss whether to pass --cfg doc. Pass --cfg doc to check builds of dependencies as part of cargo doc/rustdoc #8811
• Simliar to this issue but for config.toml. [target.'cfg(...)'] doesn't expose all keys (like test and features) #8170
• Run cargo +nightly rustc --print cfg -Zunstable-options to show a list of supported cfg expressions on your platform. You could also combine it with a custom RUSTFLAGS="--cfg X".
• I got an impression that there was an issue discussin doc-only dependencies but couldn't find it.... (edited: here it is cargo doc only direct dependencies #2025)

Footnotes

1. https://doc.rust-lang.org/nightly/cargo/reference/specifying-dependencies.html#platform-specific-dependencies ↩

[epage]

This looks to be one specific case of those covered in #8170. Closing in favor of that issue. If there is a reason we should keep this one open, let us know!