Recommend users to enable windows/docs feature when building their crate for docs.rs

[MarijnS95]

Suggestion

Our intradoc links into the windows crate don't seem to resolve on for example https://docs.rs/gpu-allocator/0.27.0/x86_64-pc-windows-msvc/gpu_allocator/d3d12/struct.Allocation.html. While I'm not exactly confident that these links are very useful, it would be nice if they resolved.

With some debugging it turns out rustdoc omits these links because it knows they are being hidden:

windows-rs/crates/libs/windows/src/lib.rs

Line 12 in f8124e8

#![cfg_attr(not(feature = "docs"), doc(hidden))]

As such, I managed to make the links resolve again locally by building with cargo doc (--no-deps) -F windows/docs

Side-note: I thought that cargo doc --no-deps would use the documentation URL from Cargo.toml for target crates, but they are ignored ¹ unless I explicitly tell rustdoc where to find the windows crate with RUSTDOCFLAGS="-Zunstable-options --extern-html-root-url=windows=https://microsoft.github.io/windows-docs-rs/doc/" cargo +nightly doc --no-deps.

---

In the end, to solve this when building our crate for docs.rs, I think the following should suffice in our Cargo.toml:

[package.metadata.docs.rs]
features = ["windows/docs"]

Footnotes

1. This appears to be a known limitation described in https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#linking-to-external-documentation. ↩

[kennykerr]

Thanks for sharing!

[MarijnS95]

Is this something we should document in the readme, the library docs, or some other place where the docs feature is described? Or do you think having this closed, searchable issue around is enough?

[kennykerr]

Yes, I think searching on GitHub is probably the most effective way of finding stuff like this.

[MarijnS95]

I'd like for folks to preempt this but it's an obscure feature.

Is this only done because docs.rs builds with all features are slow? In that case you might want to flip the cfg so that the docs are only hidden when building for docs.rs (there should be a chapter about detecting docs.rs builds) but not when built locally (assuming folks either pass --no-deps or enable a limited set of windows crate features anyway). What do you think?

[kennykerr]

Issue: #2665
PR: #2676

[kennykerr]

Eventually I'd like to move the mdbook over at kennykerr.ca to github and then it will be easier to add documentation for stuff like this.

[MarijnS95]

@kennykerr okay, so this used to be a "feature" request for windows-sys but it was transitively applied to windows as well. Despite the windows crate already being guarded by per-module feature flags (hopefully making this less of an issue, but there's a lot more code).

If it's not because of docs.rs but because of local builds being slow, that is unfortunate and breaking local doc builds if users forget to turn on the non-default docs feature.

---

Note that your second link doesn't work but it appears to be intended to link to the homepage of this repository.