Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add --cfg docsrs to all rustdoc invocations #2390

Merged
merged 3 commits into from
Feb 1, 2024
Merged

Add --cfg docsrs to all rustdoc invocations #2390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
04d987a
Fix metadata::test_features test assertion missing args
Urgau Jan 23, 2024
ca250f1
Remove -Zunstable-options from the generated cargo_args
Urgau Jan 23, 2024
697c28d
Add "--cfg docsrs" to all rustdoc invocations
Urgau Jan 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 35 additions & 22 deletions crates/metadata/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,14 +267,14 @@ 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() {
cargo_args.push("-Z".into());
cargo_args.push("unstable-options".into());
}

// Pass `RUSTFLAGS` and `RUSTDOCFLAGS` using `cargo --config`, which handles whitespace correctly.
if !self.rustc_args.is_empty() {
cargo_args.push("--config".into());
Expand Down Expand Up @@ -655,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 @@ -676,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 @@ -695,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 @@ -711,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 @@ -725,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 @@ -739,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 @@ -758,14 +767,12 @@ mod test_calculations {
String::from("rustdoc"),
"--lib".into(),
"-Zrustdoc-map".into(),
"-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);

// rustdocflags
// rustcflags
let metadata = Metadata {
rustc_args: vec!["--cfg".into(), "x".into()],
..Metadata::default()
Expand All @@ -774,10 +781,14 @@ mod test_calculations {
String::from("rustdoc"),
"--lib".into(),
"-Zrustdoc-map".into(),
"-Z".into(),
"unstable-options".into(),
"--config".into(),
"build.rustflags=[\"--cfg\", \"x\"]".into(),
"-Zhost-config".into(),
"-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 @@ -790,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
Open in desktop
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.:
Urgau marked this conversation as resolved.
Show resolved Hide resolved
{% 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
Loading