Correctly using intra-rustdoc links in no_std crates is difficult

[dylni]

AFAICT, if your crate has this line:

#![cfg_attr(not(feature = "std"), no_std)]

and you use a intra-rustdoc link for any std item, these lines must be added to build documentation with --no-default-features:

#[cfg(doc)]
extern crate std;

Then, to use items from the prelude in documentation, you'll also want:

#[cfg(doc)]
use std::prelude::v1::*

However, this defeats the purpose of the prelude being imported automatically. Would it be possible for rustdoc to add these lines even when building with #![no_std]?

This should also help solve #73423, because the std crate would always be in scope.

[jonas-schievink]

Depending on the target documentation is built for, libstd might not exist, so these lines cannot be added automatically without breaking a lot of embedded crates. However it seems like a bug that rustdoc does not inject the core library and libcore prelude instead.

[dylni]

I figured there was something I was missing about this. That seems reasonable, but the problem would still exist when mentioning items only defined in std or alloc.

I'm not sure what the best resolution for that would be, but if crates use extern crate std to have it in scope, the documentation would also fail to build on those targets. Could rustdoc default to a target that libstd is build for? It might make the link resolution more complex, but this seems like an easy thing to get wrong on the crate side.

[jyn514]

Some thoughts, not for or against this feature yet:

#[cfg(doc)]
extern crate std;

This will break if another crate depends on your docs: #75855

the problem would still exist when using items only defined in std or alloc

This is a more general problem than intra-doc links: #73423

However it seems like a bug that rustdoc does not inject the core library and libcore prelude instead.

Rustdoc should do this already, no? This works fine locally:

#![no_std]
//! Link to [`Option`]

Could rustdoc default to a target that libstd is build for?

Hmm ... that would break any crate that uses cfg(target = "...") and force crates to use cfg(any(doc, target = "...")). It is also not backwards compatible.

[jyn514]

I think I would recommend passing --feature std when documenting your crate. Adding a silent --target seems very liable to break, and adding extern crate std means that you can't document the crate for targets without the standard library.

[jyn514]

This should also help solve #73423, because the std crate would always be in scope.

Actually you just made me remember why injecting extern crate std; isn't possible - that means you can't document either std or core.

[jyn514]

I'll leave this open because I think the discussion is useful, but I don't think rustdoc is going to change it's behavior here.

[dylni]

This will break if another crate depends on your docs: #75855

I wasn't aware dependencies are built without cfg(doc). That does make the idea pretty useless.

Hmm ... that would break any crate that uses cfg(target = "...") and force crates to use cfg(any(doc, target = "...")). It is also not backwards compatible.

I'm not sure I understand, but I agree it's not a great idea.

that means you can't document either std or core.

Right, I guess this would almost require rustdoc to know how to map each item to its documentation link, which seems error-prone.

I think I would recommend passing --feature std when documenting your crate.

My specific problem is that I am using an alloc type in documentation for a #![no_std] trait. In documentation for this method, I link to ToString. If I understand correctly, if I change that link to intra-rustdoc, it will break if a reverse-dependency that doesn't use the std feature builds its documentation.

This use case might just be too hard to support.

[jyn514]

This will break if another crate depends on your docs: #75855

I wasn't aware dependencies are built without cfg(doc). That does make the idea pretty useless.

Hmm, that seems like something we could change without too much trouble. cc @rust-lang/rustdoc , what do you think about setting cfg(doc) for dependencies?

I'm not sure I understand

There could be items that are only documented on certain platforms, e.g. winapi is an empty crate on Linux. So if rustdoc overrides the target the documentation would be wrong.

My specific problem is that I am using an alloc type in documentation for a #![no_std] trait

In this particular case, if you had extern crate alloc that would work even with no_std. But in general you're correct that it would break.

[dylni]

There could be items that are only documented on certain platforms, e.g. winapi is an empty crate on Linux. So if rustdoc overrides the target the documentation would be wrong.

I see what you mean now. I actually meant that rustdoc could only use that default when resolving std links, without changing the build target. However, that wouldn't work anyway if no libstd target is installed.

In this particular case, if you had extern crate alloc that would work even with no_std.

I should have given a better example. The crate-level documentation references println!, so it still needs std.

[Manishearth]

Hmm, that seems like something we could change without too much trouble. cc @rust-lang/rustdoc , what do you think about setting cfg(doc) for dependencies?

I feel like this breaks metadata-only dep doc builds

[jyn514]

You mean like when documenting with --no-deps from cargo? I thought that didn't run rustdoc at all and only ran cargo check.

[jyn514]

I'm going to close this because I don't think it's actionable; setting cfg(doc) for dependencies seems like the only thing we could reasonably change and that's already tracked by rust-lang/cargo#8811.