cargo doc --examples doesn't pick up default features or report failure

[sowbug]

I think this is all working correctly, but I'd like to record the issue in case it trips up anyone else.

If you have a project with default features, and an example requires one of those default features to be enabled, then cargo doc --examples will give an overly general warning, fail to generate example documentation, and possibly fail to complete other generation tasks, but the invocation will report success.

E.g., suppose the correct invocation to run an example is cargo run --example hello-world --features=defaultfeature. If you omit the --features flag you'd see an error like this:

error: target `hello-world` in package `mypackage` requires the features: `defaultfeature`
Consider enabling them by passing, e.g., `--features="defaultfeature"`

This tells you exactly what to do, and all is good. But if you try a related cargo doc command cargo doc --examples, you get this error:

warning: target filter `examples` specified, but no targets matched; this is a no-op

This also makes sense; it's a batch command that doesn't have a cargo run equivalent, so it reasonably suppresses the error messages that caused the build of one example bin in the batch to fail.

But if a developer isn't really paying attention, a document-the-world command like cargo doc --no-deps --examples --workspace will appear to succeed, but generate only some of the expected documentation (in my case, it built my subcrate documentation but not the top-level crate, which was just enough for my build script to succeed without my noticing that it had actually failed to complete).

Apologies for this long-winded report; there might be a more concise description of undesirable behavior (perhaps "cargo doc --examples --workspace fails to complete if required features aren't specified"?). I have solved the issue for my own purposes and wanted to spew the whole story here in case it provides more search terms for someone else to find it.

[johndpierre1]

Can you take over everything my phone is broken

John

On Tue, Sep 3, 2024 at 7:38 PM Mike Tsao @.***> wrote:

I think this is all working correctly, but I'd like to record the issue in case it trips up anyone else.

If you have a project with default features, and an example requires one of those default features to be enabled, then cargo doc --examples will give an overly general warning, fail to generate example documentation, and possibly fail to complete other generation tasks, but the invocation will report success.

E.g., suppose the correct invocation to run an example is cargo run --example hello-world --features=defaultfeature. If you omit the --features flag you'd see an error like this:

error: target hello-world in package mypackage requires the features: defaultfeature Consider enabling them by passing, e.g., --features="defaultfeature"

This tells you exactly what to do, and all is good. But if you try a related cargo doc command cargo doc --examples, you get this error:

warning: target filter examples specified, but no targets matched; this is a no-op

This also makes sense; it's a batch command that doesn't have a cargo run equivalent, so it reasonably suppresses the error messages that caused the build of the example bin to fail.

But if a developer isn't really paying attention, a document-the-world command like cargo doc --no-deps --examples --workspace will appear to succeed, but generate only some of the expected documentation (in my case, it built my subcrate documentation but not the top-level crate, which was just enough for my build script to succeed without my noticing that it had actually failed to complete).

Apologies for this long-winded report; there might be a more concise description of undesirable behavior (perhaps "cargo doc --examples --workspace fails to complete if required features aren't specified"?). I have solved the issue for my own purposes and wanted to spew the whole story here in case it provides more search terms for someone else to find it.

— Reply to this email directly, view it on GitHub https://github.com/rust-lang/rust/issues/130560, or unsubscribe https://github.com/notifications/unsubscribe-auth/BJV6QGLYRAXL7SSMDGAWGE3ZUX62FAVCNFSM6AAAAABNSWXMHKVHI2DSMVQWIX3LMV43ASLTON2WKOZSGUYDGNJRHE3TIMI . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[syphar]

THis sounds like an issue with rustdoc , not with docs.rs,

cc @GuillaumeGomez

[sowbug]

THis sounds like an issue with rustdoc , not with docs.rs,

Good point. I'm not sure how I ended up on this issue tracker. I'll see if I can narrow the behavior to a more specific tool, and if I can, I'll move this issue. Thanks.

[syphar]

generally:

• cargo doc = rustdoc, the part of the compiler that generates the HTML files, managed as part of rustc
• docs.rs (this repo) -> a web- and build-server that builds docs for all releases, using rustdoc from above

[GuillaumeGomez]

I moved the issue to the rust repository.