There is currently no way to specify features automatically when using `cargo doc`

[GuillaumeGomez]

I thought at first about using [profile.doc], but it is doing nothing (as displayed by cargo itself) and there are no other way to do so.

Then I looked a bit deeper and noticed that you can't set features under profiles, making this not the right approach.

Therefore, I suggest adding a new section simply called "rustdoc" which would allow for now:

[rustdoc]
features = ["whatever"]

[Andlon]

In an attempt to motivate this issue, I'd like to bring up the example of proc macros that add or modify documentation, of the form

/// Foobaring a Baz.
#[modify_docs]
fn foobar(baz: Baz) {}

or

//! Crate docs
#![doc = generate_super_nice_html!()]

Or, for a more realistic example, consider the embed-doc-image crate:

//! A collection of crustaceans.
//!
//! # Ferris
//! ![Ferris](ferris)
//!
//! Ferris is a crab, as you can see in the above image.
#![doc = embed_image!("ferris", "images/ferris.png")]

A bit of a problem with these solutions is that - although the macros shown in the above examples perhaps only modify documentation, they still need to run for normal compilation. This means that:

• they might need to pull in dependencies (not dev-dependencies) that are not needed by the code in a non-documentation setting
• they generally still need to run in a non-documentation setting

For example, embed_image! will load an image from disk and encode it as base64, which might be expensive depending on the image and hardware, and as such it's conceivable that it might impact compile times in non-documentation code.

There is no truly good workaround for these kind of macros at the moment. Sure, you can define a feature that you need to manually enable when calling rustdoc, but this:

• is really annoying.
• the feature might be needed by a dependency and not something you can change from the top-level crate. So this will generally tend to break documentation for dependencies.

If we could define features that should be enabled when rustdoc is generating documentation, then we could make sure that we have zero associated costs in non-documentation settings, for example by enabling an enabled feature in the case of embed-doc-image.

[joshtriplett]

We talked about this at length in today's @rust-lang/cargo meeting. Copying some text from #10435 to move the discussion here:

Currently, Rust has three kinds of dependencies: dependencies, dev-dependencies, and build-dependencies. Adding a fourth kind of dependency would be a substantial increase in complexity.

This issue started out talking about using feature flags for this, and in our discussions today we felt like that approach would be much simpler and make more use of existing Cargo facilities.

Crates today already use features for this, and then add docs.rs metadata telling docs.rs to use those features. And features can already control dependencies or features of dependencies.

We're open to a new mechanism to automatically enable a feature flag on doc builds and doctests, so that cargo doc and cargo test work automatically. We'd be happy to discuss different ways to make that work.

Also, separately, this is something we'd consider to be a large feature, for which we'd like to see an RFC design rather than going directly to a PR. Doing design iteration in a PR is much higher bandwidth for us than reviewing an RFC.

We're also open to just installing dev-dependencies automatically when building docs. That would be a much simpler change, and (in my opinion, not speaking for the whole team here) might not require a full RFC.

[GuillaumeGomez]

The feature approach is unfortunately not sustainable as soon as the crate is a dependency because it then requires for the crate using it as a dependency to handle the feature as well. So we need a way to have dependencies and features specific to a rustdoc run. As for how, I don't have a preference. doc-dependencies seemed like the right approach but any other allowing this would be nice too.

[Andlon]

It seems to me that this issue stems from the fact that documentation and standard builds have different sets of desirable default feature sets. For example, a crate might only want to use a minimal set of features for a dependency, but when building documentation for a crate higher in the dependency tree, we still want to have the "proper" documentation for the dependencies.

However, currently there is only a single mechanism for specifying default features, with no way to distinguish between standard and doc builds.

With that in mind, it seems at first glance to me that something like the following would be ideal:

[features]
default = ["my", "default", "features"]

# Document all the default stuff, but also make sure that we document serde impls
doc-default = [ "default", "serde" ]

# If not specified, implicitly use default features, i.e.
doc-default = [ "default" ]

I think doc-default should ignore --no-default-features (command-line) and default-features = false (Cargo.toml). Otherwise documentation of dependencies might be incomplete when not using default features in the build.

Instead, we would need a separate doc-default-features = false flag (and command-line argument) so that dependencies can fine tune what they want to document from dependencies.

Certainly the latter is a breaking change: having doc builds treat default-features = false differently is a breaking change in cargo's behavior when building documentation. I'm not able to see the complete ramifications of this at the moment, and it would be great if perhaps someone from the @rust-lang/cargo team could comment on that.

[GuillaumeGomez]

Having doc-default would also allow to handle doc dependencies pretty easily. I like this suggestion!

[joshtriplett]

What is the advantage of having a doc-default feature, rather than just enabling dev-dependencies for all doc builds? doctests already have to install dev-dependencies, so this would just enable those for docs as well.