Add an option to include crate versions to the generated docs

src/bin/cargo/cli.rs

@@ -38,6 +38,7 @@ Available unstable (nightly-only) flags:
     -Z unstable-options -- Allow the usage of unstable options
     -Z timings          -- Display concurrency information
     -Z doctest-xcompile -- Compile and run doctests for non-host target using runner config
+    -Z crate-versions   -- Add crate versions to generated docs
 
 Run with 'cargo -Z [FLAG] [SUBCOMMAND]'"
         );

src/cargo/core/compiler/mod.rs

@@ -558,6 +558,7 @@ fn rustdoc<'a, 'cfg>(cx: &mut Context<'a, 'cfg>, unit: &Unit<'a>) -> CargoResult
     let mut rustdoc = cx.compilation.rustdoc_process(unit.pkg, unit.target)?;
     rustdoc.inherit_jobserver(&cx.jobserver);
     rustdoc.arg("--crate-name").arg(&unit.target.crate_name());
+    add_crate_versions_if_requested(bcx, unit, &mut rustdoc);
     add_path_args(bcx, unit, &mut rustdoc);
     add_cap_lints(bcx, unit, &mut rustdoc);
 
@@ -624,6 +625,21 @@ fn rustdoc<'a, 'cfg>(cx: &mut Context<'a, 'cfg>, unit: &Unit<'a>) -> CargoResult
     }))
 }
 
+fn add_crate_versions_if_requested(
+    bcx: &BuildContext<'_, '_>,
+    unit: &Unit<'_>,
+    rustdoc: &mut ProcessBuilder,
+) {
+    if !bcx.config.cli_unstable().crate_versions {
+        return;
+    }
+    rustdoc
+        .arg("-Z")
+        .arg("unstable-options")
+        .arg("--crate-version")
+        .arg(&unit.pkg.version().to_string());
+}
+
 // The path that we pass to rustc is actually fairly important because it will
 // show up in error messages (important for readability), debug information
 // (important for caching), etc. As a result we need to be pretty careful how we

src/cargo/core/features.rs

@@ -342,6 +342,7 @@ pub struct CliUnstable {
     pub panic_abort_tests: bool,
     pub jobserver_per_rustc: bool,
     pub features: Option<Vec<String>>,
+    pub crate_versions: bool,
 }
 
 impl CliUnstable {
@@ -418,6 +419,7 @@ impl CliUnstable {
             "panic-abort-tests" => self.panic_abort_tests = parse_empty(k, v)?,
             "jobserver-per-rustc" => self.jobserver_per_rustc = parse_empty(k, v)?,
             "features" => self.features = Some(parse_features(v)),
+            "crate-versions" => self.crate_versions = parse_empty(k, v)?,
             _ => bail!("unknown `-Z` flag specified: {}", k),
         }
 

src/doc/src/reference/unstable.md

@@ -541,3 +541,10 @@ The available options are:
 
 * `compare` — This option compares the resolved features to the old resolver,
   and will print any differences.
+
+### crate-versions
+* Tracking Issue: [#7907](https://github.com/rust-lang/cargo/issues/7907)
+
+The `-Z crate-versions` flag will make `cargo doc` include appropriate crate versions for the current crate and all of its dependencies (unless `--no-deps` was provided) in the compiled documentation.
+
+You can find an example screenshot for the cargo itself in the tracking issue.

tests/testsuite/doc.rs

@@ -1510,3 +1510,36 @@ fn bin_private_items_deps() {
     assert!(p.root().join("target/doc/bar/fn.bar_pub.html").is_file());
     assert!(!p.root().join("target/doc/bar/fn.bar_priv.html").exists());
 }
+
+#[cargo_test]
+fn crate_versions() {
+    // Testing unstable flag
+    if !is_nightly() {
+        return;
+    }
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "1.2.4"
+            authors = []
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("-Z crate-versions doc")
+        .masquerade_as_nightly_cargo()
+        .run();
+
+    let doc_file = p.root().join("target/doc/foo/index.html");
+    let mut doc_html = String::new();
+    File::open(&doc_file)
+        .unwrap()
+        .read_to_string(&mut doc_html)
+        .unwrap();
+
+    assert!(doc_html.contains("Version 1.2.4"));
+}