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
into my 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 rustdoc
flags:
[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.