cargo
cargo copied to clipboard
rust-lang
Optionally document dev-dependencies
Currently cargo doc will build documentation for the crate and its dependencies, which is useful as (outside of the core Rust distribution) you get a one stop shop of documentation while working on a crate, however as far as I could see "dev-dependencies" can't be included in that.
This is inconvenient for test-support libraries and for complex "examples" e.g. in a library crate you want a binary which depends on docopt/clap or ncurses or winapi or the Ruby C API or some other large dependency which is completely unnecessary for the core library, but you don't want to fork it to a separate crate, so you make it an example and use dev dependencies, however you've now lost offline access to the "large dependency"'s documentation.
Sounds like a good idea to me! I could imagine something like cargo doc --dev or something like that for this.
It will be done soon! Just been focusing on cargo fix --clippy for the time being, almost done with that though I think.
It's worth to mention that when you run cargo test your dev-dependencies crates are used in checking your docs example code. But when you build documentation (cargo +nightly doc) these crates are ignored in links.
warning: unresolved link to `static_bytes::SafeBytesSlice`
--> src/mac/frame/mod.rs:279:29
|
279 | /// [`SafeBytesSlice`]: static_bytes::SafeBytesSlice
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unresolved link
|
= note: `#[warn(broken_intra_doc_links)]` on by default
= help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
warning: 1 warning emitted
Version:
cargo +nightly version
cargo 1.47.0-nightly (51b66125b 2020-08-19)
Any progress here? What are some next steps? Any way I can help?
I'd really appreciate this feature because I frequently do "offline" development where I run cargo doc, then go offline and having the dev dependency docs is often important since I try to spend a lot of dev effort on improving tests.
Current workaround is to add your dev-dependencies under [dependencies] in Cargo.toml, run cargo doc, then comment added dependencies. As long as you don't clean target/doc, they will still be there even if your run cargo doc again.
