Auto merge of rust-lang#117888 - notriddle:notriddle/releases, r=Mark-Simulacrum

doc: add release notes to standalone doc bundle

Preview: http://notriddle.com/rustdoc-html-demo-5/release-notes/releases.html

This is a workaround for rust-lang#101714 on top of being a useful addition in its own right. It is intended to change the "canonical URL" for viewing the release notes from GitHub, which is relatively slow, to a pre-rendered HTML file that loads from the same CDN as the standard library docs. It also means you get a copy of the release notes when installing the rust-docs with rustup.

Author: bors

src/bootstrap/src/core/build_steps/doc.rs

@@ -7,8 +7,9 @@
 //! Everything here is basically just a shim around calling either `rustbook` or
 //! `rustdoc`.
 
-use std::fs;
+use std::io::{self, Write};
 use std::path::{Path, PathBuf};
+use std::{fs, mem};
 
 use crate::core::build_steps::compile;
 use crate::core::build_steps::tool::{self, prepare_tool_cargo, SourceType, Tool};
@@ -388,6 +389,104 @@ impl Step for Standalone {
     }
 }
 
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub struct Releases {
+    compiler: Compiler,
+    target: TargetSelection,
+}
+
+impl Step for Releases {
+    type Output = ();
+    const DEFAULT: bool = true;
+
+    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
+        let builder = run.builder;
+        run.path("RELEASES.md").alias("releases").default_condition(builder.config.docs)
+    }
+
+    fn make_run(run: RunConfig<'_>) {
+        run.builder.ensure(Releases {
+            compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
+            target: run.target,
+        });
+    }
+
+    /// Generates HTML release notes to include in the final docs bundle.
+    ///
+    /// This uses the same stylesheet and other tools as Standalone, but the
+    /// RELEASES.md file is included at the root of the repository and gets
+    /// the headline added. In the end, the conversion is done by Rustdoc.
+    fn run(self, builder: &Builder<'_>) {
+        let target = self.target;
+        let compiler = self.compiler;
+        let _guard = builder.msg_doc(compiler, "releases", target);
+        let out = builder.doc_out(target);
+        t!(fs::create_dir_all(&out));
+
+        builder.ensure(Standalone {
+            compiler: builder.compiler(builder.top_stage, builder.config.build),
+            target,
+        });
+
+        let version_info = builder.ensure(SharedAssets { target: self.target }).version_info;
+
+        let favicon = builder.src.join("src/doc/favicon.inc");
+        let footer = builder.src.join("src/doc/footer.inc");
+        let full_toc = builder.src.join("src/doc/full-toc.inc");
+
+        let html = out.join("releases.html");
+        let tmppath = out.join("releases.md");
+        let inpath = builder.src.join("RELEASES.md");
+        let rustdoc = builder.rustdoc(compiler);
+        if !up_to_date(&inpath, &html)
+            || !up_to_date(&footer, &html)
+            || !up_to_date(&favicon, &html)
+            || !up_to_date(&full_toc, &html)
+            || !(builder.config.dry_run()
+                || up_to_date(&version_info, &html)
+                || up_to_date(&rustdoc, &html))
+        {
+            let mut tmpfile = t!(fs::File::create(&tmppath));
+            t!(tmpfile.write_all(b"% Rust Release Notes\n\n"));
+            t!(io::copy(&mut t!(fs::File::open(&inpath)), &mut tmpfile));
+            mem::drop(tmpfile);
+            let mut cmd = builder.rustdoc_cmd(compiler);
+
+            // Needed for --index-page flag
+            cmd.arg("-Z").arg("unstable-options");
+
+            cmd.arg("--html-after-content")
+                .arg(&footer)
+                .arg("--html-before-content")
+                .arg(&version_info)
+                .arg("--html-in-header")
+                .arg(&favicon)
+                .arg("--markdown-no-toc")
+                .arg("--markdown-css")
+                .arg("rust.css")
+                .arg("--index-page")
+                .arg(&builder.src.join("src/doc/index.md"))
+                .arg("--markdown-playground-url")
+                .arg("https://play.rust-lang.org/")
+                .arg("-o")
+                .arg(&out)
+                .arg(&tmppath);
+
+            if !builder.config.docs_minification {
+                cmd.arg("--disable-minification");
+            }
+
+            builder.run(&mut cmd);
+        }
+
+        // We open doc/RELEASES.html as the default if invoked as `x.py doc --open RELEASES.md`
+        // with no particular explicit doc requested (e.g. library/core).
+        if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
+            builder.open_in_browser(&html);
+        }
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct SharedAssetsPaths {
     pub version_info: PathBuf,

src/bootstrap/src/core/builder.rs

@@ -810,6 +810,7 @@ impl<'a> Builder<'a> {
                 doc::StyleGuide,
                 doc::Tidy,
                 doc::Bootstrap,
+                doc::Releases,
             ),
             Kind::Dist => describe!(
                 dist::Docs,

src/doc/index.md

@@ -4,12 +4,6 @@
 nav {
     display: none;
 }
-body {
-    font-family: serif;
-}
-h1, h2, h3, h4, h5, h6 {
-    font-family: sans-serif;
-}
 h3 {
     font-size: 1.35rem;
 }
@@ -119,10 +113,14 @@ documentation for your project _and_ all its dependencies in their correct
 version, and open it in your browser. Add the flag `--document-private-items` to
 also show items not marked `pub`.
 
-### The Edition Guide
+### Rust Version History
+
+[The Release Notes](releases.html) describes the change history of the Rust
+toolchain and language.
 
 [The Edition Guide](edition-guide/index.html) describes the Rust editions and
-their differences.
+their differences. The latest version of the toolchain supports all
+historical editions.
 
 ### The `rustc` Book
 

src/doc/rust.css

@@ -1,6 +1,7 @@
 /* General structure */
 
 body {
+	font-family: serif;
 	margin: 0 auto;
 	padding: 0 15px;
 	font-size: 18px;
@@ -17,6 +18,9 @@ body {
 	}
 }
 
+h1, h2, h3, h4, h5, h6 {
+	font-family: sans-serif;
+}
 h2, h3, h4, h5, h6 {
 	font-weight: 400;
 	line-height: 1.1;