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.79.0-nightly (4d570eea0 2024-04-26).

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 your Rust code, you can test for the docsrs cfg, e.g.:

#[cfg(docsrs)]
mod documentation;

The `docsrs` cfg only applies to the final rustdoc invocation (i.e. the crate currently being documented). It does not apply to dependencies (including workspace ones).

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

if std::env::var("DOCS_RS").is_ok() {
    // ... your code here ...
}

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

Cross-compiling

All targets other than x86_64-unknown-linux-gnu are cross-compiled. For implementation reasons, this is unlikely to change for the foreseeable future.

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", "my_cfg"]

Here, the compiler arguments are set so that #[cfg(my_cfg)] (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	6 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:

• Network access will not be enabled for any crate.
• Any crate that requests a time extension will be limited to one target.

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.