Hi all documentation enthusiasts,
Now that Rust 1.48 is out, I've started using intra-doc links in my projects. So I wrote things like this:
//! # Cargo Features //! //! The textwrap library has two optional features: //! //! * `terminal_size`: enables automatic detection of the terminal //! width via the [terminal_size] crate.
This works great if I generate the documentation using
cargo doc --all-features. However, if I leave out the flag, I get a warning since there is no
terminal_size crate then:
warning: unresolved link to `terminal_size` --> src/lib.rs:79:22 | 79 | //! width via the [terminal_size] crate. See the | ^^^^^^^^^^^^^ no item named `terminal_size` in scope | = note: `#[warn(broken_intra_doc_links)]` on by default = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
Luckily, I can put
[package.metadata.docs.rs] all-features = true
Cargo.toml file to have docs.rs render things fine — is there a similar way to have
cargo doc work out of the box when I run it locally?
I tried playing with a
.cargo/config.toml file where I tried overriding
cargo doc and tried setting the
[alias] doc = ["doc", "--all-features"] [build] rustdocflags = ["--cfg", 'feature="terminal_size"']
Neither worked: you're unfortunately not allowed to override builtin commands with the
[alias] section and changing
build.rustdocflags didn't seem to have any effect — though this might very well be me who doesn't understand what to pass here
Any advice? Note that I'm not just linking to the optional dependencies, I'm also sometimes referring to conditionally available methods in my own code.