From 29f5d2c1aedc37ec0040504b73e6c9ac5a8c97c1 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Mon, 13 Nov 2023 15:09:24 -0700 Subject: [PATCH 1/3] doc: add release notes to standalone doc bundle This is a workaround for #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. --- src/bootstrap/src/core/build_steps/doc.rs | 103 +++++++++++++++++++++- src/bootstrap/src/core/builder.rs | 1 + src/doc/index.md | 14 ++- src/doc/rust.css | 4 + 4 files changed, 113 insertions(+), 9 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index e3fd942fc3802..3b8110e52e43b 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/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,106 @@ 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 all standalone documentation as compiled by the rustdoc in `stage` + /// for the `target` into `out`. + /// + /// This will list all of `src/doc` looking for markdown files and appropriately + /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and + /// `STAMP` along with providing the various header/footer HTML we've customized. + /// + /// In the end, this is just a glorified wrapper around 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)) + || !(builder.config.dry_run() || 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::(Kind::Doc) { + builder.open_in_browser(&html); + } + } +} + #[derive(Debug, Clone)] pub struct SharedAssetsPaths { pub version_info: PathBuf, diff --git a/src/bootstrap/src/core/builder.rs b/src/bootstrap/src/core/builder.rs index cd276674dee6b..861b2bdecb528 100644 --- a/src/bootstrap/src/core/builder.rs +++ b/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, diff --git a/src/doc/index.md b/src/doc/index.md index 7c97c16c20bdc..8ad5b427b552a 100644 --- a/src/doc/index.md +++ b/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 diff --git a/src/doc/rust.css b/src/doc/rust.css index d33ab0326031f..e0bf64c33bcf0 100644 --- a/src/doc/rust.css +++ b/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; From a3d90036c5d3f25fd08a0517a63b28eed5365dd0 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sat, 18 Nov 2023 14:05:59 -0700 Subject: [PATCH 2/3] Do not call dry_run twice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Onur Özkan --- src/bootstrap/src/core/build_steps/doc.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 3b8110e52e43b..0f960ab4965c3 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -445,8 +445,9 @@ impl Step for Releases { || !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)) - || !(builder.config.dry_run() || up_to_date(&rustdoc, &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")); From 0bf77206ad8fc72cc5970ced6a2126b07afbddb0 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sun, 19 Nov 2023 08:01:17 -0700 Subject: [PATCH 3/3] Fix outdated doc comment on Releases doc build step --- src/bootstrap/src/core/build_steps/doc.rs | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 0f960ab4965c3..834f88dc891e8 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/src/bootstrap/src/core/build_steps/doc.rs @@ -411,14 +411,11 @@ impl Step for Releases { }); } - /// Generates all standalone documentation as compiled by the rustdoc in `stage` - /// for the `target` into `out`. + /// Generates HTML release notes to include in the final docs bundle. /// - /// This will list all of `src/doc` looking for markdown files and appropriately - /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and - /// `STAMP` along with providing the various header/footer HTML we've customized. - /// - /// In the end, this is just a glorified wrapper around rustdoc! + /// 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;