Skip to content

Commit

Permalink
Add "--cfg docsrs" to all rustdoc invocations
Browse files Browse the repository at this point in the history
  • Loading branch information
@Urgau @syphar
Urgau authored and syphar committed Feb 1, 2024
1 parent a29f0af commit 240d3e8
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 14 deletions.
42 changes: 30 additions & 12 deletions crates/metadata/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,12 @@ impl Metadata {
cargo_args.push("--no-default-features".into());
}

let mut all_rustdoc_args = self.rustdoc_args.clone();
// Unconditionnaly set `--cfg docsrs` as it has become a de-facto way to
// distinguish docs.rs.
//
// See https://github.com/rust-lang/docs.rs/issues/2389.
let mut all_rustdoc_args = vec!["--cfg".into(), "docsrs".into()];
all_rustdoc_args.extend_from_slice(&self.rustdoc_args);
all_rustdoc_args.extend_from_slice(rustdoc_args);

// Pass `RUSTFLAGS` and `RUSTDOCFLAGS` using `cargo --config`, which handles whitespace correctly.
Expand Down Expand Up @@ -650,14 +655,20 @@ mod test_targets {
mod test_calculations {
use super::*;

fn default_cargo_args() -> Vec<String> {
vec!["rustdoc".into(), "--lib".into(), "-Zrustdoc-map".into()]
fn default_cargo_args(extra_args: &[String]) -> Vec<String> {
let mut args = vec!["rustdoc".into(), "--lib".into(), "-Zrustdoc-map".into()];
args.extend_from_slice(extra_args);
args.extend_from_slice(&[
"--config".into(),
r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(),
]);
args
}

#[test]
fn test_defaults() {
let metadata = Metadata::default();
assert_eq!(metadata.cargo_args(&[], &[]), default_cargo_args());
assert_eq!(metadata.cargo_args(&[], &[]), default_cargo_args(&[]));
let env = metadata.environment_variables();
assert_eq!(env.get("DOCS_RS").map(String::as_str), Some("1"));
assert!(env.get("RUSTDOCFLAGS").is_none());
Expand All @@ -671,17 +682,15 @@ mod test_calculations {
all_features: true,
..Metadata::default()
};
let mut expected_args = default_cargo_args();
expected_args.push("--all-features".into());
let expected_args = default_cargo_args(&["--all-features".into()]);
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

// no default features
let metadata = Metadata {
no_default_features: true,
..Metadata::default()
};
let mut expected_args = default_cargo_args();
expected_args.push("--no-default-features".into());
let expected_args = default_cargo_args(&["--no-default-features".into()]);
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

// allow passing both even though it's nonsense; cargo will give an error anyway
Expand All @@ -690,9 +699,8 @@ mod test_calculations {
no_default_features: true,
..Metadata::default()
};
let mut expected_args = default_cargo_args();
expected_args.push("--all-features".into());
expected_args.push("--no-default-features".into());
let expected_args =
default_cargo_args(&["--all-features".into(), "--no-default-features".into()]);
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

// explicit empty vec
Expand All @@ -706,6 +714,8 @@ mod test_calculations {
"-Zrustdoc-map".into(),
"--features".into(),
String::new(),
"--config".into(),
r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

Expand All @@ -720,6 +730,8 @@ mod test_calculations {
"-Zrustdoc-map".into(),
"--features".into(),
"some_feature".into(),
"--config".into(),
r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

Expand All @@ -734,6 +746,8 @@ mod test_calculations {
"-Zrustdoc-map".into(),
"--features".into(),
"feature1 feature2".into(),
"--config".into(),
r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

Expand All @@ -754,7 +768,7 @@ mod test_calculations {
"--lib".into(),
"-Zrustdoc-map".into(),
"--config".into(),
r#"build.rustdocflags=["-Z", "unstable-options", "--static-root-path", "/", "--cap-lints", "warn"]"#.into(),
r#"build.rustdocflags=["--cfg", "docsrs", "-Z", "unstable-options", "--static-root-path", "/", "--cap-lints", "warn"]"#.into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

Expand All @@ -773,6 +787,8 @@ mod test_calculations {
"-Ztarget-applies-to-host".into(),
"--config".into(),
"host.rustflags=[\"--cfg\", \"x\"]".into(),
"--config".into(),
"build.rustdocflags=[\"--cfg\", \"docsrs\"]".into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);

Expand All @@ -785,6 +801,8 @@ mod test_calculations {
String::from("rustdoc"),
"--lib".into(),
"-Zrustdoc-map".into(),
"--config".into(),
"build.rustdocflags=[\"--cfg\", \"docsrs\"]".into(),
"-Zbuild-std".into(),
];
assert_eq!(metadata.cargo_args(&[], &[]), expected_args);
Expand Down
13 changes: 11 additions & 2 deletions templates/core/about/builds.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,15 @@ <h4 id="setting-a-readme"> <a href="#setting-a-readme">Setting a README</a> </h4
</p>

<h4 id="detecting-docsrs"> <a href="#detecting-docsrs">Detecting Docs.rs</a> </h4>
<p>
To recognize Docs.rs from your Rust code, you can test for the <code>docsrs</code> cfg, e.g.:
{% filter highlight(lang="rust") %}{% filter dedent(levels=3) -%}
#[cfg(docsrs)]
mod documentation;
{%- endfilter %}{% endfilter %}
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).
</p>
<p>
To recognize Docs.rs from <code>build.rs</code> files, you can test for the environment variable <code>DOCS_RS</code>, e.g.:
{% filter highlight(lang="rust") %}{% filter dedent(levels=3) -%}
Expand All @@ -48,9 +57,9 @@ <h4 id="cross-compiling"> <a href="#cross-compiling">Cross-compiling</a> </h4>
You can configure how your crate is built by adding <a href="metadata">package metadata</a> to your <code>Cargo.toml</code>, e.g.:
{% filter highlight(lang="toml") %}{% filter dedent -%}
[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "my_cfg"]
{%- endfilter %}{% endfilter %}
Here, the compiler arguments are set so that <code>#[cfg(docsrs)]</code> (not to be confused with <code>#[cfg(doc)]</code>) can be used for conditional compilation.
Here, the compiler arguments are set so that <code>#[cfg(my_cfg)]</code> (not to be confused with <code>#[cfg(doc)]</code>) can be used for conditional compilation.
This approach is also useful for setting <a href="https://doc.rust-lang.org/cargo/reference/features.html">cargo features</a>.
</p>

Expand Down

0 comments on commit 240d3e8

Please sign in to comment.