Support documenting Cargo

The primary motivation is to have the cargo docs show up on https://doc.rust-lang.org/nightly/nightly-rustc/cargo, but as a nice side effect this makes `x doc cargo` work locally.
rust-lang · Dec 22, 2022 · f94c926 · f94c926
1 parent e5e4eef
commit f94c926
Show file tree

Hide file tree

Showing 5 changed files with 160 additions and 24 deletions.
diff --git a/Cargo.lock b/Cargo.lock
@@ -77,6 +77,15 @@ dependencies = [
  "yansi-term",
 ]
 
+[[package]]
+name = "ansi_term"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee49baf6cb617b853aa8d93bf420db2383fab46d314482ca2803b40d5fde979b"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "ansi_term"
 version = "0.12.1"
@@ -707,7 +716,7 @@ dependencies = [
  "declare_clippy_lint",
  "if_chain",
  "itertools",
- "pulldown-cmark",
+ "pulldown-cmark 0.9.2",
  "quine-mc_cluskey",
  "regex-syntax",
  "rustc-semver",
@@ -1028,6 +1037,16 @@ dependencies = [
  "quote",
 ]
 
+[[package]]
+name = "ctor"
+version = "0.1.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d2301688392eb071b0bf1a37be05c469d3cc4dbbd95df672fe28ab021e6a096"
+dependencies = [
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "curl"
 version = "0.4.44"
@@ -1104,6 +1123,12 @@ version = "0.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "56254986775e3233ffa9c4d7d3faaf6d36a2c09d30b20687e9f88bc8bafc16c8"
 
+[[package]]
+name = "difference"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "524cbf6897b527295dff137cec09ecf3a05f4fddffd7dfcd1585403449e74198"
+
 [[package]]
 name = "digest"
 version = "0.10.2"
@@ -1683,6 +1708,21 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "handlebars"
+version = "3.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4498fc115fa7d34de968184e473529abb40eeb6be8bc5f7faba3d08c316cb3e3"
+dependencies = [
+ "log",
+ "pest",
+ "pest_derive",
+ "quick-error 2.0.1",
+ "serde",
+ "serde_json",
+ "walkdir",
+]
+
 [[package]]
 name = "handlebars"
 version = "4.3.3"
@@ -1794,7 +1834,7 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df004cfca50ef23c36850aaaa59ad52cc70d0e90243c3c7737a4dd32dc7a3c4f"
 dependencies = [
- "quick-error",
+ "quick-error 1.2.3",
 ]
 
 [[package]]
@@ -1990,19 +2030,19 @@ dependencies = [
 
 [[package]]
 name = "io-lifetimes"
-version = "1.0.2"
+version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e394faa0efb47f9f227f1cd89978f854542b318a6f64fa695489c9c993056656"
+checksum = "46112a93252b123d31a119a8d1a1ac19deac4fac6e0e8b0df58f0d4e5870e63c"
 dependencies = [
  "libc",
  "windows-sys",
 ]
 
 [[package]]
 name = "is-terminal"
-version = "0.4.0"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aae5bc6e2eb41c9def29a3e0f1306382807764b9b53112030eff57435667352d"
+checksum = "28dfb6c8100ccc63462345b67d1bbc3679177c75ee4bf59bf29c8b1d110b8189"
 dependencies = [
  "hermit-abi 0.2.6",
  "io-lifetimes",
@@ -2221,9 +2261,9 @@ dependencies = [
 
 [[package]]
 name = "linux-raw-sys"
-version = "0.1.3"
+version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f9f08d8963a6c613f4b1a78f4f4a4dbfadf8e6545b2d72861731e4858b8b47f"
+checksum = "f051f77a7c8e6957c0696eac88f26b0117e54f52d3fc682ab19397a8812846a4"
 
 [[package]]
 name = "litemap"
@@ -2328,12 +2368,12 @@ dependencies = [
  "clap_complete",
  "elasticlunr-rs",
  "env_logger 0.9.0",
- "handlebars",
+ "handlebars 4.3.3",
  "lazy_static",
  "log",
  "memchr",
  "opener",
- "pulldown-cmark",
+ "pulldown-cmark 0.9.2",
  "regex",
  "serde",
  "serde_json",
@@ -2343,6 +2383,19 @@ dependencies = [
  "topological-sort",
 ]
 
+[[package]]
+name = "mdman"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "handlebars 3.5.5",
+ "pretty_assertions",
+ "pulldown-cmark 0.7.2",
+ "same-file",
+ "serde_json",
+ "url",
+]
+
 [[package]]
 name = "measureme"
 version = "10.1.0"
@@ -2617,6 +2670,15 @@ version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e22443d1643a904602595ba1cd8f7d896afe56d26712531c5ff73a15b2fbf64"
 
+[[package]]
+name = "output_vt100"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "628223faebab4e3e40667ee0b2336d34a5b960ff60ea743ddfdbcf7770bcfb66"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "owo-colors"
 version = "3.4.0"
@@ -2858,6 +2920,18 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"
 
+[[package]]
+name = "pretty_assertions"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f81e1644e1b54f5a68959a29aa86cde704219254669da328ecfdf6a1f09d427"
+dependencies = [
+ "ansi_term 0.11.0",
+ "ctor",
+ "difference",
+ "output_vt100",
+]
+
 [[package]]
 name = "pretty_env_logger"
 version = "0.4.0"
@@ -2933,6 +3007,17 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca36dea94d187597e104a5c8e4b07576a8a45aa5db48a65e12940d3eb7461f55"
+dependencies = [
+ "bitflags",
+ "memchr",
+ "unicase",
+]
+
 [[package]]
 name = "pulldown-cmark"
 version = "0.9.2"
@@ -2956,6 +3041,12 @@ version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quine-mc_cluskey"
 version = "0.2.4"
@@ -4545,7 +4636,7 @@ dependencies = [
  "itertools",
  "minifier",
  "once_cell",
- "pulldown-cmark",
+ "pulldown-cmark 0.9.2",
  "rayon",
  "regex",
  "rustdoc-json-types",
@@ -5375,7 +5466,7 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "245da694cc7fc4729f3f418b304cb57789f1bed2a78c575407ab8a23f53cb4d3"
 dependencies = [
- "ansi_term",
+ "ansi_term 0.12.1",
  "lazy_static",
  "matchers",
  "parking_lot 0.11.2",
@@ -5394,7 +5485,7 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ce989c9962c7f61fe084dd4a230eec784649dfc2392467c790007c3a6e134e7"
 dependencies = [
- "ansi_term",
+ "ansi_term 0.12.1",
  "atty",
  "tracing-core",
  "tracing-log",

diff --git a/Cargo.toml b/Cargo.toml
@@ -25,6 +25,8 @@ members = [
   "src/tools/cargo/crates/credential/cargo-credential-1password",
   "src/tools/cargo/crates/credential/cargo-credential-macos-keychain",
   "src/tools/cargo/crates/credential/cargo-credential-wincred",
+  "src/tools/cargo/crates/mdman",
+  # "src/tools/cargo/crates/resolver-tests",
   "src/tools/rustdoc",
   "src/tools/rls",
   "src/tools/rustfmt",

diff --git a/src/bootstrap/builder.rs b/src/bootstrap/builder.rs
@@ -702,6 +702,7 @@ impl<'a> Builder<'a> {
                 doc::RustdocBook,
                 doc::RustByExample,
                 doc::RustcBook,
+                doc::Cargo,
                 doc::CargoBook,
                 doc::Clippy,
                 doc::ClippyBook,

diff --git a/src/bootstrap/doc.rs b/src/bootstrap/doc.rs
@@ -729,7 +729,7 @@ impl Step for Rustc {
 }
 
 macro_rules! tool_doc {
-    ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => {
+    ($tool: ident, $should_run: literal, $path: literal, $(rustc_tool = $rustc_tool:literal, )? $(in_tree = $in_tree:literal, )? [$($krate: literal),+ $(,)?] $(,)?) => {
         #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
         pub struct $tool {
             target: TargetSelection,
@@ -763,13 +763,24 @@ macro_rules! tool_doc {
                 let out = builder.compiler_doc_out(target);
                 t!(fs::create_dir_all(&out));
 
-                // Build rustc docs so that we generate relative links.
-                builder.ensure(Rustc { stage, target });
-                // Rustdoc needs the rustc sysroot available to build.
-                // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
-                // with strange errors, but only on a full bors test ...
                 let compiler = builder.compiler(stage, builder.config.build);
-                builder.ensure(compile::Rustc::new(compiler, target));
+                builder.ensure(compile::Std::new(compiler, target));
+
+                if true $(&& $rustc_tool)? {
+                    // Build rustc docs so that we generate relative links.
+                    builder.ensure(Rustc { stage, target });
+
+                    // Rustdoc needs the rustc sysroot available to build.
+                    // FIXME: is there a way to only ensure `check::Rustc` here? Last time I tried it failed
+                    // with strange errors, but only on a full bors test ...
+                    builder.ensure(compile::Rustc::new(compiler, target));
+                }
+
+                let source_type = if true $(&& $in_tree)? {
+                    SourceType::InTree
+                } else {
+                    SourceType::Submodule
+                };
 
                 builder.info(
                     &format!(
@@ -781,9 +792,15 @@ macro_rules! tool_doc {
                 );
 
                 // Symlink compiler docs to the output directory of rustdoc documentation.
-                let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc");
-                t!(fs::create_dir_all(&out_dir));
-                t!(symlink_dir_force(&builder.config, &out, &out_dir));
+                let out_dirs = [
+                    builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc"),
+                    // Cargo uses a different directory for proc macros.
+                    builder.stage_out(compiler, Mode::ToolRustc).join("doc"),
+                ];
+                for out_dir in out_dirs {
+                    t!(fs::create_dir_all(&out_dir));
+                    t!(symlink_dir_force(&builder.config, &out, &out_dir));
+                }
 
                 // Build cargo command.
                 let mut cargo = prepare_tool_cargo(
@@ -793,7 +810,7 @@ macro_rules! tool_doc {
                     target,
                     "doc",
                     $path,
-                    SourceType::InTree,
+                    source_type,
                     &[],
                 );
 
@@ -824,6 +841,30 @@ tool_doc!(
 );
 tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]);
 tool_doc!(Miri, "miri", "src/tools/miri", ["miri"]);
+tool_doc!(
+    Cargo,
+    "cargo",
+    "src/tools/cargo",
+    rustc_tool = false,
+    in_tree = false,
+    [
+        "cargo",
+        "cargo-platform",
+        "cargo-util",
+        "crates-io",
+        "cargo-test-macro",
+        "cargo-test-support",
+        "cargo-credential",
+        "cargo-credential-1password",
+        "mdman",
+        // FIXME: this trips a license check in tidy.
+        // "resolver-tests",
+        // FIXME: we should probably document these, but they're different per-platform so we can't use `tool_doc`.
+        // "cargo-credential-gnome-secret",
+        // "cargo-credential-macos-keychain",
+        // "cargo-credential-wincred",
+    ]
+);
 
 #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct ErrorIndex {

diff --git a/src/bootstrap/lib.rs b/src/bootstrap/lib.rs
@@ -202,6 +202,7 @@ const EXTRA_CHECK_CFGS: &[(Option<Mode>, &'static str, Option<&[&'static str]>)]
     (None, "bootstrap", None),
     (Some(Mode::Rustc), "parallel_compiler", None),
     (Some(Mode::ToolRustc), "parallel_compiler", None),
+    (Some(Mode::ToolRustc), "emulate_second_only_system", None),
     (Some(Mode::Codegen), "parallel_compiler", None),
     (Some(Mode::Std), "stdarch_intel_sde", None),
     (Some(Mode::Std), "no_fp_fmt_parse", None),