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
Urgau committed Jan 23, 2024
1 parent d5a652f commit 4cc7801
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 15 deletions.
44 changes: 31 additions & 13 deletions crates/metadata/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -267,10 +267,15 @@ 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);

if !self.rustc_args.is_empty() || !all_rustdoc_args.is_empty() {
if !self.rustc_args.is_empty() || all_rustdoc_args.len() > 2 {
cargo_args.push("-Z".into());
cargo_args.push("unstable-options".into());
}
Expand Down Expand Up @@ -655,14 +660,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 @@ -676,17 +687,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 @@ -695,9 +704,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 @@ -711,6 +719,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 @@ -725,6 +735,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 @@ -739,6 +751,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 @@ -761,7 +775,7 @@ mod test_calculations {
"-Z".into(),
"unstable-options".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 @@ -782,6 +796,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 @@ -794,6 +810,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
11 changes: 9 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,13 @@ <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 %}
</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 +55,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 4cc7801

Please sign in to comment.