bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Use a macro for documenting rustdoc

Browse source
This commit is contained in:
Joshua Nelson 2021-06-29 23:05:02 -04:00
parent 0ce21126b2
commit 81f3ab6bca
2 changed files with 76 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/bootstrap/builder.rs
View file

@ -465,6 +465,7 @@ impl<'a> Builder<'a> {
doc::Std, doc::Std,
doc::Rustc, doc::Rustc,
doc::Rustdoc, doc::Rustdoc,
// doc::Rustfmt,
doc::ErrorIndex, doc::ErrorIndex,
doc::Nomicon, doc::Nomicon,
doc::Reference, doc::Reference,

143
src/bootstrap/doc.rs
View file

@ -593,84 +593,91 @@ impl Step for Rustc {
} }
} }
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)] macro_rules! tool_doc {
pub struct Rustdoc { ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?]) => {
stage: u32, #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
target: TargetSelection, pub struct $tool {
} stage: u32,
target: TargetSelection,
impl Step for Rustdoc {
type Output = ();
const DEFAULT: bool = true;
const ONLY_HOSTS: bool = true;
fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
run.krate("rustdoc-tool")
}
fn make_run(run: RunConfig<'_>) {
run.builder.ensure(Rustdoc { stage: run.builder.top_stage, target: run.target });
}
/// Generates compiler documentation.
///
/// This will generate all documentation for compiler and dependencies.
/// Compiler documentation is distributed separately, so we make sure
/// we do not merge it with the other documentation from std, test and
/// proc_macros. This is largely just a wrapper around `cargo doc`.
fn run(self, builder: &Builder<'_>) {
let stage = self.stage;
let target = self.target;
builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
// This is the intended out directory for compiler documentation.
let out = builder.compiler_doc_out(target);
t!(fs::create_dir_all(&out));
let compiler = builder.compiler(stage, builder.config.build);
if !builder.config.compiler_docs {
builder.info("\tskipping - compiler/librustdoc docs disabled");
return;
} }
// Build rustc docs so that we generate relative links. impl Step for $tool {
builder.ensure(Rustc { stage, target }); type Output = ();
const DEFAULT: bool = true;
const ONLY_HOSTS: bool = true;
// Build rustdoc. fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
builder.ensure(tool::Rustdoc { compiler }); run.krate($should_run)
}
// Symlink compiler docs to the output directory of rustdoc documentation. fn make_run(run: RunConfig<'_>) {
let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target.triple).join("doc"); run.builder.ensure($tool { stage: run.builder.top_stage, target: run.target });
t!(fs::create_dir_all(&out_dir)); }
t!(symlink_dir_force(&builder.config, &out, &out_dir));
// Build cargo command. /// Generates compiler documentation.
let mut cargo = prepare_tool_cargo( ///
builder, /// This will generate all documentation for compiler and dependencies.
compiler, /// Compiler documentation is distributed separately, so we make sure
Mode::ToolRustc, /// we do not merge it with the other documentation from std, test and
target, /// proc_macros. This is largely just a wrapper around `cargo doc`.
"doc", fn run(self, builder: &Builder<'_>) {
"src/tools/rustdoc", let stage = self.stage;
SourceType::InTree, let target = self.target;
&[], builder.info(&format!("Documenting stage{} {} ({})", stage, stringify!($tool).to_lowercase(), target));
);
cargo.arg("-Zskip-rustdoc-fingerprint"); // This is the intended out directory for compiler documentation.
// Only include compiler crates, no dependencies of those, such as `libc`. let out = builder.compiler_doc_out(target);
cargo.arg("--no-deps"); t!(fs::create_dir_all(&out));
cargo.arg("-p").arg("rustdoc");
cargo.arg("-p").arg("rustdoc-json-types");
cargo.rustdocflag("--document-private-items"); let compiler = builder.compiler(stage, builder.config.build);
cargo.rustdocflag("--enable-index-page");
cargo.rustdocflag("--show-type-layout"); if !builder.config.compiler_docs {
cargo.rustdocflag("-Zunstable-options"); builder.info("\tskipping - compiler/tool docs disabled");
builder.run(&mut cargo.into()); return;
}
// Build rustc docs so that we generate relative links.
builder.ensure(Rustc { stage, target });
// Build the tool.
builder.ensure(tool::$tool { compiler });
// 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));
// Build cargo command.
let mut cargo = prepare_tool_cargo(
builder,
compiler,
Mode::ToolRustc,
target,
"doc",
$path,
SourceType::InTree,
&[],
);
cargo.arg("-Zskip-rustdoc-fingerprint");
// Only include compiler crates, no dependencies of those, such as `libc`.
cargo.arg("--no-deps");
$(
cargo.arg("-p").arg($krate);
)+
cargo.rustdocflag("--document-private-items");
cargo.rustdocflag("--enable-index-page");
cargo.rustdocflag("--show-type-layout");
cargo.rustdocflag("-Zunstable-options");
builder.run(&mut cargo.into());
}
}
} }
} }
tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"]);
#[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)] #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub struct ErrorIndex { pub struct ErrorIndex {
pub target: TargetSelection, pub target: TargetSelection,