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

All crates are built in a sandbox using the nightly release of the Rust compiler. The current version in use isrustc 1.87.0-nightly (75530e9f7 2025-03-18).

Notes on using Docs.rs

Setting a README

The README of a crate is taken from thereadme field defined inCargo.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 thedocsrs cfg, e.g.:

#[cfg(docsrs)]moddocumentation;

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 frombuild.rs files, you can test for the environment variableDOCS_RS, e.g.:

ifstd::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 thanx86_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 addingpackage metadata to yourCargo.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 settingcargo features.

Testing documentation builds locally

The Docs.rsREADME 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 throughcrates-build-env. SeeForge 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 yourbuild.rs generates files that are relevant for documentation, consider writing to thecargo output directory, passed in the environment variableOUT_DIR.

Hitting resource limits

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

Available RAM	6.44 GB
Maximum rustdoc execution time	15 minutes
Maximum size of a build log	102.40 kB
Network access	blocked
Maximum number of build targets	10

If your build fails because it hit one of these limits, pleaseopen 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, pleasefile 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.