Builds

Docs.rs automatically builds documentation for crates released on crates.io. It may take a while to build your crate, depending on how many crates are in the queue.

All crates are built in a sandbox using the nightly release of the Rust compiler. The current version in use is rustc 1.48.0-nightly (bbc677480 2020-09-18).

Notes on using Docs.rs

Setting a README

The README of a crate is taken from the readme field defined in Cargo.toml. If this field is not set, no README will be displayed.

Detecting Docs.rs

To recognize Docs.rs from build.rs files, you can test for the environment variable DOCS_RS, e.g.:


if let Ok(_) = std::env::var("DOCS_RS") {
    // ... your code here ...
}        

This approach can be helpful if you need dependencies for building the library, but not for building the documentation.

You can configure how your crate is built by adding package metadata to your Cargo.toml, e.g.:


[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]

Here, the compiler arguments are set so that #[cfg(docsrs)] (not to be confused with #[cfg(doc)]) can be used for conditional compilation. This approach is also useful for setting cargo features.

Testing documentation builds locally

The Docs.rs README describes how to build unpublished crate documentation locally using the same build environment as the Docs.rs build agent.

Diagnosing failed builds

Missing dependencies

Missing dependencies are a common reason for failed builds. Docs.rs dependencies are managed through crates-build-env. See Forge for how to add a dependency.

Write attempt on read-only directories

Most of the sandbox is a read-only file system, including the source directory of your crate and its dependencies. If your build.rs generates files that are relevant for documentation, consider writing to the cargo output directory, passed in the environment variable OUT_DIR.

Hitting resource limits

All the builds are executed inside a sandbox with limited resources. The current limits are:

Available RAM 3 GB
Maximum rustdoc execution time 15 minutes
Maximum size of a build log 100 KB
Network access blocked
Maximum number of build targets 10

If your build fails because it hit one of these limits, please open an issue to get them increased for your crate. Since our build agent has finite resources, we have to consider each case individually. However, there are a few general policies:

Other failures and requesting rebuilds

If your crate fails to build for a reason not listed here, please file an issue. Some build failures can be fixed by Docs.rs, e.g., by issuing a rebuild after a bug in Docs.rs has been fixed.