mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #102706 - ferrocene:pa-ignore-doc-index, r=jyn514

Browse Source 
Support excluding the generation of the standalone docs

For Ferrocene we need to exclude the generation of the standalone docs (which include the index page, which we want to replace with our own), but with the way bootstrap is currently implemented that proved not possible. This PR aims to support that.

The first problem is that the `doc::Standalone` step did two things: it generated the "standalone" documentation (which includes the index page and all the pages at the root of the documentation tree), but it also generated some files like `rust.css` and `version_info.html` that other step like `doc::TheBook` required. This meant generating the book required generating the index page, which made disabling the index page generation problematic.

The approach I took to fix the first problem is to split the step into `doc::Standalone` and `doc::SharedAssets`, with `doc::TheBook` now depending on `doc::SharedAssets`.

The second problem is that disabling the `doc::Standalone` proved to be tricky due to its path, `src/doc`. The path is accurate, as the source files for that step are `src/doc/*.md`. The problem is, bootstrap treats `--exclude` as a *suffix*, and so it also excluded the Cargo book whose source lives at `src/tools/cargo/src/doc`.

The approach I took to fix the second problem is to add the `standalone` path in addition to `src/doc`, so that you can pass `--exclude standalone`. I'm not fully happy with the solution, and the other idea I had was to just move the standalone docs source code to `src/doc/standalone`. I feel that second approach is cleaner, but also requires more changes and might require more consensus.

This PR is best reviewed commit-by-commit.

r? `@jyn514`
This commit is contained in:
Dylan DPC 2022-10-26 17:32:54 +05:30 committed by GitHub
commit b03fa1a3fe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
src/bootstrap/doc.rs
View File

@ -228,7 +228,7 @@ fn run(self, builder: &Builder<'_>) {
}
// build the version info page and CSS
builder.ensure(Standalone { compiler, target });
let shared_assets = builder.ensure(SharedAssets { target });
// build the redirect pages
builder.info(&format!("Documenting book redirect pages ({})", target));
@ -237,7 +237,7 @@ fn run(self, builder: &Builder<'_>) {
let path = file.path();
let path = path.to_str().unwrap();
invoke_rustdoc(builder, compiler, target, path);
invoke_rustdoc(builder, compiler, &shared_assets, target, path);
}
if builder.was_invoked_explicitly::<Self>(Kind::Doc) {
@ -251,6 +251,7 @@ fn run(self, builder: &Builder<'_>) {
fn invoke_rustdoc(
builder: &Builder<'_>,
compiler: Compiler,
shared_assets: &SharedAssetsPaths,
target: TargetSelection,
markdown: &str,
) {
@ -260,7 +261,6 @@ fn invoke_rustdoc(
let header = builder.src.join("src/doc/redirect.inc");
let footer = builder.src.join("src/doc/footer.inc");
let version_info = out.join("version_info.html");
let mut cmd = builder.rustdoc_cmd(compiler);
@ -269,7 +269,7 @@ fn invoke_rustdoc(
cmd.arg("--html-after-content")
.arg(&footer)
.arg("--html-before-content")
.arg(&version_info)
.arg(&shared_assets.version_info)
.arg("--html-in-header")
.arg(&header)
.arg("--markdown-no-toc")
@ -300,7 +300,7 @@ impl Step for Standalone {
fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
let builder = run.builder;
run.path("src/doc").default_condition(builder.config.docs)
run.path("src/doc").alias("standalone").default_condition(builder.config.docs)
}
fn make_run(run: RunConfig<'_>) {
@ -325,21 +325,11 @@ fn run(self, builder: &Builder<'_>) {
let out = builder.doc_out(target);
t!(fs::create_dir_all(&out));
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");
t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
let version_input = builder.src.join("src/doc/version_info.html.template");
let version_info = out.join("version_info.html");
if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
let info = t!(fs::read_to_string(&version_input))
.replace("VERSION", &builder.rust_release())
.replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
.replace("STAMP", builder.rust_info.sha().unwrap_or(""));
t!(fs::write(&version_info, &info));
}
for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
let file = t!(file);
@ -401,6 +391,45 @@ fn run(self, builder: &Builder<'_>) {
}
}
#[derive(Debug, Clone)]
pub struct SharedAssetsPaths {
pub version_info: PathBuf,
}
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub struct SharedAssets {
target: TargetSelection,
}
impl Step for SharedAssets {
type Output = SharedAssetsPaths;
const DEFAULT: bool = false;
fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
// Other tasks depend on this, no need to execute it on its own
run.never()
}
// Generate shared resources used by other pieces of documentation.
fn run(self, builder: &Builder<'_>) -> Self::Output {
let out = builder.doc_out(self.target);
let version_input = builder.src.join("src").join("doc").join("version_info.html.template");
let version_info = out.join("version_info.html");
if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
let info = t!(fs::read_to_string(&version_input))
.replace("VERSION", &builder.rust_release())
.replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
.replace("STAMP", builder.rust_info.sha().unwrap_or(""));
t!(fs::write(&version_info, &info));
}
builder.copy(&builder.src.join("src").join("doc").join("rust.css"), &out.join("rust.css"));
SharedAssetsPaths { version_info }
}
}
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub struct Std {
pub stage: u32,
@ -429,7 +458,8 @@ fn run(self, builder: &Builder<'_>) {
let target = self.target;
let out = builder.doc_out(target);
t!(fs::create_dir_all(&out));
t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
builder.ensure(SharedAssets { target: self.target });
let index_page = builder.src.join("src/doc/index.md").into_os_string();
let mut extra_args = vec![