Add unstable rustdoc option --crate-list-heading.

When used, this option creates a subheading within the sidebar
“Crates” list for this crate and all crates which pass the same value.
These headings are displayed in alphabetical order; crates without the
option, or with it set to the empty string, always appear first.

The intended use of this option is to allow Cargo to automatically
separate a workspace’s crate list into the workspace’s own crates
and their external dependencies. Authors could also use RUSTDOCFLAGS
or other means to create custom headings for their documentation builds.

Author: kpreid

src/librustdoc/config.rs

@@ -241,6 +241,10 @@ pub(crate) struct RenderOptions {
     /// What sorting mode to use for module pages.
     /// `ModuleSorting::Alphabetical` by default.
     pub(crate) module_sorting: ModuleSorting,
+    /// In the sidebar list of all crates, put the current crate(s) under this heading.
+    /// To put a crate under the unnamed primary heading, which is always listed first,
+    /// make this the empty string.
+    pub(crate) crate_list_heading: String,
     /// List of themes to extend the docs with. Original argument name is included to assist in
     /// displaying errors if it fails a theme check.
     pub(crate) themes: Vec<StylePath>,
@@ -760,6 +764,7 @@ impl Options {
         } else {
             ModuleSorting::Alphabetical
         };
+        let crate_list_heading = matches.opt_str("crate-list-heading").unwrap_or_default();
         let resource_suffix = matches.opt_str("resource-suffix").unwrap_or_default();
         let markdown_no_toc = matches.opt_present("markdown-no-toc");
         let markdown_css = matches.opt_strs("markdown-css");
@@ -859,6 +864,7 @@ impl Options {
             id_map,
             playground_url,
             module_sorting,
+            crate_list_heading,
             themes,
             extension_css,
             extern_html_root_urls,

src/librustdoc/html/render/write_shared.rs

@@ -13,6 +13,7 @@
 //!    --resource-suffix flag and are emitted when --emit-type is empty (default)
 //!    or contains "invocation-specific".
 
+use std::borrow::Cow;
 use std::cell::RefCell;
 use std::ffi::OsString;
 use std::fs::File;
@@ -69,8 +70,13 @@ pub(crate) fn write_shared(
     write_search_desc(cx, krate, &desc)?; // does not need to be merged
 
     let crate_name = krate.name(cx.tcx());
-    let crate_name = crate_name.as_str(); // rand
-    let crate_name_json = OrderedJson::serialize(crate_name).unwrap(); // "rand"
+    let crate_name = crate_name.as_str(); // e.g. rand
+    let crate_name_json = OrderedJson::serialize(AllCratesEntry {
+        heading: Cow::Borrowed(&opt.crate_list_heading),
+        crate_name: Cow::Borrowed(crate_name),
+    })
+    .unwrap(); // e.g. {"c":"rand","h":""}
+
     let external_crates = hack_get_external_crate_names(&cx.dst, &cx.shared.resource_suffix)?;
     let info = CrateInfo {
         version: CrateInfoVersion::V1,
@@ -387,6 +393,19 @@ impl AllCratesPart {
     }
 }
 
+/// Type of a serialized entry in the [`AllCratesPart`] JSON.
+#[derive(Serialize, Deserialize, Clone, Default, Debug)]
+struct AllCratesEntry<'a> {
+    #[serde(rename = "c")]
+    crate_name: Cow<'a, str>,
+
+    /// If non-absent and non-empty, is the name of a section heading in the crate sidebar.
+    #[serde(rename = "h")]
+    #[serde(default)]
+    #[serde(skip_serializing_if = "str::is_empty")]
+    heading: Cow<'a, str>,
+}
+
 /// Reads `crates.js`, which seems like the best
 /// place to obtain the list of externally documented crates if the index
 /// page was disabled when documenting the deps.
@@ -408,8 +427,12 @@ fn hack_get_external_crate_names(
     let Some(content) = regex.find(&content) else {
         return Err(Error::new("could not find crates list in crates.js", path));
     };
-    let content: Vec<String> = try_err!(serde_json::from_str(content.as_str()), &path);
-    Ok(content)
+    let crate_names: Vec<String> =
+        try_err!(serde_json::from_str::<Vec<AllCratesEntry<'static>>>(content.as_str()), &path)
+            .into_iter()
+            .map(|entry| entry.crate_name.into_owned())
+            .collect();
+    Ok(crate_names)
 }
 
 #[derive(Serialize, Deserialize, Clone, Default, Debug)]

src/librustdoc/html/render/write_shared/tests.rs

@@ -9,7 +9,8 @@ fn hack_external_crate_names() {
     let path = path.path();
     let crates = hack_get_external_crate_names(&path, "").unwrap();
     assert!(crates.is_empty());
-    fs::write(path.join("crates.js"), r#"window.ALL_CRATES = ["a","b","c"];"#).unwrap();
+    fs::write(path.join("crates.js"), r#"window.ALL_CRATES = [{"c":"a"},{"c":"b"},{"c":"c"}];"#)
+        .unwrap();
     let crates = hack_get_external_crate_names(&path, "").unwrap();
     assert_eq!(crates, ["a".to_string(), "b".to_string(), "c".to_string()]);
 }

src/librustdoc/html/static/js/main.js

@@ -994,6 +994,7 @@ function preLoadCss(cssUrl) {
         window.register_type_impls(window.pending_type_impls);
     }
 
+    // Draw a convenient sidebar of known crates if we have a listing
     function addSidebarCrates() {
         if (!window.ALL_CRATES) {
             return;
@@ -1002,26 +1003,58 @@ function preLoadCss(cssUrl) {
         if (!sidebarElems) {
             return;
         }
-        // Draw a convenient sidebar of known crates if we have a listing
-        const h3 = document.createElement("h3");
-        h3.innerHTML = "Crates";
-        const ul = document.createElement("ul");
-        ul.className = "block crate";
 
-        for (const crate of window.ALL_CRATES) {
-            const link = document.createElement("a");
-            link.href = window.rootPath + crate + "/index.html";
-            link.textContent = crate;
+        const allCratesHeading = document.createElement("h3");
+        allCratesHeading.textContent = "Crates";
 
-            const li = document.createElement("li");
-            if (window.rootPath !== "./" && crate === window.currentCrate) {
-                li.className = "current";
+        const allCratesSection = document.createElement("section");
+
+        // window.ALL_CRATES is in unsorted array-of-structs format; reorganize so crates with the
+        // same heading are grouped.
+        const cratesGroupedByHeading = new Map();
+        for (const entry of window.ALL_CRATES) {
+            const heading = entry.h;
+            const crateName = entry.c;
+            let group = cratesGroupedByHeading.get(heading);
+            if (group === undefined) {
+                group = [];
+                cratesGroupedByHeading.set(heading, group);
+            }
+            group.push(crateName);
+        }
+        const headings = Array.from(cratesGroupedByHeading.keys());
+        headings.sort();
+
+        // Generate HTML for grouped crates.
+        for (const headingText of headings) {
+            // Empty string denotes a group with no named heading.
+            if (headingText !== "") {
+                const crateCategoryHeading = document.createElement("h4");
+                crateCategoryHeading.textContent = headingText;
+                allCratesSection.appendChild(crateCategoryHeading);
+            }
+
+            const cratesUl = document.createElement("ul");
+            cratesUl.className = "block crate";
+
+            for (const crateName of cratesGroupedByHeading.get(headingText)) {
+                const link = document.createElement("a");
+                link.href = window.rootPath + crateName + "/index.html";
+                link.textContent = crateName;
+
+                const li = document.createElement("li");
+                if (window.rootPath !== "./" && crateName === window.currentCrate) {
+                    li.className = "current";
+                }
+                li.appendChild(link);
+                cratesUl.appendChild(li);
             }
-            li.appendChild(link);
-            ul.appendChild(li);
+
+            allCratesSection.appendChild(cratesUl);
         }
-        sidebarElems.appendChild(h3);
-        sidebarElems.appendChild(ul);
+
+        sidebarElems.appendChild(allCratesHeading);
+        sidebarElems.appendChild(allCratesSection);
     }
 
     function expandAllDocs() {

src/librustdoc/html/static/js/rustdoc.d.ts

@@ -14,7 +14,7 @@ declare global {
         /** Make the current theme easy to find */
         currentTheme: HTMLLinkElement|null;
         /** List of all documented crates. */
-        ALL_CRATES: string[]|undefined;
+        ALL_CRATES: rustdoc.AllCratesEntry[]|undefined;
         /** Used by the popover tooltip code. */
         RUSTDOC_TOOLTIP_HOVER_MS: number;
         /** Used by the popover tooltip code. */
@@ -396,6 +396,18 @@ declare namespace rustdoc {
         bindings: Map<number, FingerprintableType[]>;
     };
 
+    /** Member of ALL_CRATES. */
+    interface AllCratesEntry {
+        /**
+         * Heading under which the crate should be listed.
+         * 
+         * May be empty to specify the first, primary heading.
+         */
+        h: string,
+        /** Crate name. */
+        c: string,
+    }
+
     /**
      * The raw search data for a given crate. `n`, `t`, `d`, `i`, and `f`
      * are arrays with the same length. `q`, `a`, and `c` use a sparse

src/librustdoc/lib.rs

@@ -383,6 +383,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "sort modules by where they appear in the program, rather than alphabetically",
             "",
         ),
+        opt(
+            Unstable,
+            Opt,
+            "",
+            "crate-list-heading",
+            "heading under which to list this crate in the sidebar crate list",
+            "PATH",
+        ),
         opt(
             Stable,
             Opt,

tests/rustdoc/crate-list-heading.rs

@@ -0,0 +1,5 @@
+//@ compile-flags: -Zunstable-options --crate-list-heading=helloworld
+#![crate_name = "foo"]
+
+//@ hasraw crates.js '"h":"helloworld"'
+//@ hasraw crates.js '"c":"foo"'