Intra-doc links that rely on dev-dependencies don't work

[jplatte]

This section of axum's documentation contains a bunch of broken intra-doc links, mostly to tower-http (bug report). It looks like the culprit here is that somehow, dev-dependencies are excluded when docs.rs builds the docs, which means that most of tower-http's features aren't activated, so the modules we want to link to don't exist and rustdoc just inserts the intra-doc link verbatim.

[Nemo157]

dev-dependencies are never active when building docs. What may be happening to make your local doc build work is intra-workspace feature leakage; one of your other crates activates a feature that then allows the links to resolve. If I delete the workspace Cargo.toml then try building the docs in axum/axum I get unresolved link warnings. (For some reason cargo tree --edges=features doesn't show any differences though...)

[Nemo157]

Ok, no, somehow the dev-dependencies features are getting activated when it is in a workspace. This seems like some kind of cargo bug.

[jplatte]

I thought intra-workspace feature leakage would only affect cargo commands ran from the workspace root? I made sure to also test when inside the axum directory.

So if this is expected behavior, is there a suggested workaround? I guess we could declare a __docs feature that also enables the needed features on tower(-http).

[Nemo157]

I guess we could declare a __docs feature that also enables the needed features on tower(-http).

Yeah, that's what I would probably do.

[jplatte]

Alright. Are you going to report this weird behavior to Cargo? If yes, can you then link it here? If not I'll work on making a small repro so I know I understand the problem and raise a bug report myself some time soon.

In any case, there doesn't seem to be anything to track here.

[Nemo157]

Reported in rust-lang/cargo#10909

[Nemo157]

And relevant upstream issue to improve the support for this: rust-lang/cargo#8905