Open sowbug opened 1 month ago
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 packagemypackage
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-opThis 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: @.***>
THis sounds like an issue with rustdoc , not with docs.rs,
cc @GuillaumeGomez
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.
generally:
cargo doc
= rustdoc, the part of the compiler that generates the HTML files, managed as part of rustc I moved the issue to the rust repository.
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:This tells you exactly what to do, and all is good. But if you try a related
cargo doc
commandcargo doc --examples
, you get this error: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.