docs.rs failing to resolve links to feature gated items even though all-features is set to true

[sam0x17]

This is for the crate macro_magic: https://crates.io/crates/macro_magic

On this page I have some links to some things that are feature-gated within my crate: https://docs.rs/macro_magic/0.2.12/macro_magic/attr.export_tokens.html

Notice that the links to things in syn and local feature gated items are all broken (this did not happen before the feature gating).

I deal with this by always running cargo doc locally with cargo doc --all-features. Under these conditions all the links resolve fine and everything in my crate is properly documented.

To get this to work in docs.rs, I was told to add the following to my Cargo.toml, which I did several versions ago.

[package.metadata.docs.rs]
all-features = true

However, docs.rs still isn't resolving links to any of the feature gated items, whether they be to items in optional external crates like syn, or local constants and things that are feature gated. Links to anything feature gated will not work.

Strangely, however, I am able to go to the doc pages for those things, I just can't link to them. I think this is a legitimate bug in docs.rs

That said, happy to hear if there is a quick fix as I'm mostly just trying to fix my docs and I haven't seen this be an issue for other similar crates so I don't know what is going on

[Nemo157]

Seems like it's a bug in recent rustdoc, testing locally with cargo rustdoc -Z rustdoc-map --all-features --config "doc.extern-map.registries.crates-io=\"https://docs.rs/{pkg_name}/{version}/x86_64-unknown-linux-gnu\"" it correctly linked when built with a few months old nightly but failed to link with the most recent. I see that cargo is passing the --extern-html-root-url 'syn=https://docs.rs/syn/1.0.109/x86_64-unknown-linux-gnu' flag in so it's not a cargo issue, and seems unrelated to feature gating.

[Nemo157]

After some manual bisection I feel pretty confident that rust-lang/rust#94857 was the cause. The macro here is a re-export which previously would have the link resolved during the final doc-build of macro_magic, but now the links get resolved during the build of macro_magic_macros and fail to resolve since --extern-html-root-url isn't passed (and in-fact can't be passed since rustc doesn't support it).

[Nemo157]

Opened rust-lang/rust#110183 about it.

[sam0x17]

Note that this seems to be occurring even for a pub const (not in a proc macro crate) in my case, but hopefully what you're mentioning @Nemo157 is the root cause

edit: if you browse around the docs, you'll see broken links to regular items in the macro_magic_core crate as well, which is a non proc macro crate whose presence is feature gated

[Nemo157]

Do you mean like the [`MACRO_MAGIC_ROOT`] on https://docs.rs/macro_magic/0.2.12/macro_magic/attr.import_tokens_attr.html? I would expect any external intra-doc-links from the re-exported proc-macro items to be broken.

There are actually two macro_magic_core's involved, the proc-macro's dependency and the normal crate's dependency are treated as different crates. When doing the rustdoc build the --extern-html-root-url=magic_macro_core=... passed applies only to the normal crate's dependency, not the proc-macro's dependency, which is why links from the re-exports in https://docs.rs/macro_magic/0.2.12/macro_magic/mm_core/index.html work, but not links from the proc-macro re-exports.

[syphar]

@Nemo157 do I understand correctly that rust-lang/rust#110183 is the actual issue, which means we could close this one here?

[Nemo157]

Yep, we can't really do anything till rust-lang/rust#110183 is fixed, once that is we could do a rebuild of the crate (though it looks like the new versions makes these non-links, we could rebuild the old version to verify it starts working then @sam0x17 could revert those changes to get the links finally).