Docs.rs: Detecting docs.rs from build.rs?

[kornelski]

I have a crate that requires complicated system dependencies to build. However, the real functionality is not actually needed for docs, so I think I could fake it just for doc generation.

Can I somehow detect docs.rs and build my crate differently for docs?

[onur]

Thanks for the neat idea, currently there is no way to check this.

We can setup an environment variable and you can check presence of this env var to detect if build machine is docs.rs. What do you think?

[kornelski]

Yes, that would work.

[waywardmonkeys]

Is there any update on this or something that I can do to help out?

[epage]

As a terrible workaround, what about creating a docs-rs feature that stubs out your -sys dependencies? You can then use the package.metadata.docs.rs.features table in Cargo.toml to enable that feature.

[kornelski]

There could be docs.rs-specific solution (e.g. the site could set a feature or env var), but ideally this could be built-in into Rust.

Tests get cfg(test), so perhaps docs should get cfg(doc)?

If there was an officially blessed solution, then it would be easier to make crates like pkg-config-rs solve the problem for all users (e.g. it could ignore pkg-config errors when cfg(doc)).

[pkgw]

See @nickbabcock's comment in #191 for a clever-but-hacky workaround:

[package.metadata.docs.rs]
rustc-args = ["--cfg",  "<name>_docs_rs"]
rustdoc-args = ["--cfg", "<name>_docs_rs"]

Then in build.rs you can do things like:

if cfg!(<name>_docs_rs) { ... }

[kornelski]

I wasn't aware of the metadata table!

[package.metadata.docs.rs]
features = [ "docs-only" ]

That would work for me.

[ogoffart]

The [package.metadata.docs.rs] features = [ "docs-only" ] Did not work for me while attempting a generic solution for the cpp crate (https://github.com/mystor/rust-cpp/pull/57 )
The first problem is that i forgot to add a [feature] docs-only=[] then the compilation of the cpp_build failed in https://docs.rs/crate/cpp_build/0.5.2/builds/165974 I did not know this was required. But that's easy to fix.

A more complicated problem is that it seems that this package.metadata.docs.rs] only work when generating the documentation for the crate itself, but not when compiling the dependencies.
So a crate that depends on cpp_build did not try to compile it with the feature, as this can be seen in https://docs.rs/crate/qmetaobject/0.1.0/builds/165979 :

   Compiling cpp_build v0.5.2

This succeed, while it should have failed (because of the missing [feature] section in cpp-build) Therefore showing that the feature was not passed to the crate.

Any idea how to solve this?

[jyn514]

cfg(doc) is now native to rustdoc, would that solve your issue?

[retep998]

Can that be detected by build scripts?

[jyn514]

Hmm, I don't think so. I'll see if we can add an environment variable.

[jyn514]

Mentoring instructions:

• In execute_build, set an environment variable when calling cargo (maybe DOCS_RS=1?). It would be nice to add a link to this issue as a comment as well.
• Add documentation to templates/about.hbs, maybe near the top where we mention the version of rustc being used.

See also the contributing guidelines. Feel free to reach out here or on the Discord #docs-rs channel if you need help!

[jyn514]

docs.rs now sets DOCS_RS=1 when compiling crates.