rfc#3662 changes under unstable flags

* All new functionality is under unstable options
* Adds `--merge=shared|none|finalize` flags
* Adds `--parts-out-dir=<crate specific directory>` for `--merge=none`
to write cross-crate info file for a single crate
* Adds `--include-parts-dir=<previously specified directory>` for
`--merge=finalize` to write cross-crate info files
* update tests/run-make/rustdoc-default-output/rmake.rs golden

Author: EtomicBomb

src/librustdoc/config.rs

@@ -53,6 +53,14 @@ impl TryFrom<&str> for OutputFormat {
 }
 }
 
+/// Either an input crate, markdown file, or nothing (--merge=finalize).
+pub(crate)enumInputMode{
+/// The `--merge=finalize` step does not need an input crate to rustdoc.
+NoInputMergeFinalize,
+/// A crate or markdown file.
+HasFile(Input),
+}
+
 /// Configuration options for rustdoc.
 #[derive(Clone)]
 pub(crate)structOptions{
@@ -286,6 +294,12 @@ pub(crate) struct RenderOptions {
 /// This field is only used for the JSON output. If it's set to true, no file will be created
 /// and content will be displayed in stdout directly.
 pub(crate)output_to_stdout:bool,
+/// Whether we should read or write rendered cross-crate info in the doc root.
+pub(crate)should_merge:ShouldMerge,
+/// Path to crate-info for external crates.
+pub(crate)include_parts_dir:Vec<PathToParts>,
+/// Where to write crate-info
+pub(crate)parts_out_dir:Option<PathToParts>,
 }
 
 #[derive(Copy,Clone,Debug,PartialEq,Eq)]
@@ -345,7 +359,7 @@ impl Options {
 early_dcx:&mutEarlyDiagCtxt,
 matches:&getopts::Matches,
 args:Vec<String>,
-) -> Option<(Input,Options,RenderOptions)>{
+) -> Option<(InputMode,Options,RenderOptions)>{
 // Check for unstable options.
  nightly_options::check_nightly_options(early_dcx, matches,&opts());
 
@@ -475,22 +489,34 @@ impl Options {
 let(lint_opts, describe_lints, lint_cap) = get_cmd_lint_options(early_dcx, matches);
 
 let input = if describe_lints {
-""// dummy, this won't be used
+InputMode::HasFile(make_input(early_dcx,""))
 }else{
 match matches.free.as_slice(){
+[]if matches.opt_str("merge").as_deref() == Some("finalize") => {
+InputMode::NoInputMergeFinalize
+}
 [] => dcx.fatal("missing file operand"),
-[input] => input,
+[input] => InputMode::HasFile(make_input(early_dcx,input)),
  _ => dcx.fatal("too many file operands"),
 }
 };
-let input = make_input(early_dcx, input);
 
 let externs = parse_externs(early_dcx, matches,&unstable_opts);
 let extern_html_root_urls = matchparse_extern_html_roots(matches){
 Ok(ex) => ex,
 Err(err) => dcx.fatal(err),
 };
 
+let parts_out_dir =
+match matches.opt_str("parts-out-dir").map(|p| PathToParts::from_flag(p)).transpose(){
+Ok(parts_out_dir) => parts_out_dir,
+Err(e) => dcx.fatal(e),
+};
+let include_parts_dir = matchparse_include_parts_dir(matches){
+Ok(include_parts_dir) => include_parts_dir,
+Err(e) => dcx.fatal(e),
+};
+
 let default_settings:Vec<Vec<(String,String)>> = vec![
  matches
 .opt_str("default-theme")
@@ -732,6 +758,10 @@ impl Options {
 let extern_html_root_takes_precedence =
  matches.opt_present("extern-html-root-takes-precedence");
 let html_no_source = matches.opt_present("html-no-source");
+let should_merge = matchparse_merge(matches){
+Ok(result) => result,
+Err(e) => dcx.fatal(format!("--merge option error: {e}")),
+};
 
 if generate_link_to_definition && (show_coverage || output_format != OutputFormat::Html){
  dcx.struct_warn(
@@ -819,6 +849,9 @@ impl Options {
 no_emit_shared:false,
  html_no_source,
  output_to_stdout,
+ should_merge,
+ include_parts_dir,
+ parts_out_dir,
 };
 Some((input, options, render_options))
 }
@@ -894,3 +927,71 @@ fn parse_extern_html_roots(
 }
 Ok(externs)
 }
+
+/// Path directly to crate-info file.
+///
+/// For example, `/home/user/project/target/doc.parts/<crate>/crate-info`.
+#[derive(Clone,Debug)]
+pub(crate)structPathToParts(pub(crate)PathBuf);
+
+implPathToParts{
+fnfrom_flag(path:String) -> Result<PathToParts,String>{
+letmut path = PathBuf::from(path);
+// check here is for diagnostics
+if path.exists() && !path.is_dir(){
+Err(format!(
+"--parts-out-dir and --include-parts-dir expect directories, found: {}",
+ path.display(),
+))
+}else{
+// if it doesn't exist, we'll create it. worry about that in write_shared
+ path.push("crate-info");
+Ok(PathToParts(path))
+}
+}
+}
+
+/// Reports error if --include-parts-dir / crate-info is not a file
+fnparse_include_parts_dir(m:&getopts::Matches) -> Result<Vec<PathToParts>,String>{
+letmut ret = Vec::new();
+for p in m.opt_strs("include-parts-dir"){
+let p = PathToParts::from_flag(p)?;
+// this is just for diagnostic
+if !p.0.is_file(){
+returnErr(format!("--include-parts-dir expected {} to be a file", p.0.display()));
+}
+ ret.push(p);
+}
+Ok(ret)
+}
+
+/// Controls merging of cross-crate information
+#[derive(Debug,Clone)]
+pub(crate)structShouldMerge{
+/// Should we append to existing cci in the doc root
+pub(crate)read_rendered_cci:bool,
+/// Should we write cci to the doc root
+pub(crate)write_rendered_cci:bool,
+}
+
+/// Extracts read_rendered_cci and write_rendered_cci from command line arguments, or
+/// reports an error if an invalid option was provided
+fnparse_merge(m:&getopts::Matches) -> Result<ShouldMerge,&'staticstr>{
+match m.opt_str("merge").as_deref(){
+// default = read-write
+None => Ok(ShouldMerge{read_rendered_cci:true,write_rendered_cci:true}),
+Some("none")if m.opt_present("include-parts-dir") => {
+Err("--include-parts-dir not allowed if --merge=none")
+}
+Some("none") => Ok(ShouldMerge{read_rendered_cci:false,write_rendered_cci:false}),
+Some("shared")if m.opt_present("parts-out-dir") || m.opt_present("include-parts-dir") => {
+Err("--parts-out-dir and --include-parts-dir not allowed if --merge=shared")
+}
+Some("shared") => Ok(ShouldMerge{read_rendered_cci:true,write_rendered_cci:true}),
+Some("finalize")if m.opt_present("parts-out-dir") => {
+Err("--parts-out-dir not allowed if --merge=finalize")
+}
+Some("finalize") => Ok(ShouldMerge{read_rendered_cci:false,write_rendered_cci:true}),
+Some(_) => Err("argument to --merge must be `none`, `shared`, or `finalize`"),
+}
+}

src/librustdoc/html/render/context.rs

@@ -16,12 +16,11 @@ use tracing::info;
 
 usesuper::print_item::{full_path, item_path, print_item};
 usesuper::sidebar::{print_sidebar, sidebar_module_like,ModuleLike,Sidebar};
-usesuper::write_shared::write_shared;
 usesuper::{collect_spans_and_sources, scrape_examples_help,AllTypes,LinkFromSrc,StylePath};
 usecrate::clean::types::ExternalLocation;
 usecrate::clean::utils::has_doc_flag;
 usecrate::clean::{self,ExternalCrate};
-usecrate::config::{ModuleSorting,RenderOptions};
+usecrate::config::{ModuleSorting,RenderOptions,ShouldMerge};
 usecrate::docfs::{DocFS,PathError};
 usecrate::error::Error;
 usecrate::formats::cache::Cache;
@@ -30,6 +29,7 @@ use crate::formats::FormatRenderer;
 usecrate::html::escape::Escape;
 usecrate::html::format::{join_with_double_colon,Buffer};
 usecrate::html::markdown::{self, plain_text_summary,ErrorCodes,IdMap};
+usecrate::html::render::write_shared::write_shared;
 usecrate::html::url_parts_builder::UrlPartsBuilder;
 usecrate::html::{layout, sources, static_files};
 usecrate::scrape_examples::AllCallLocations;
@@ -128,8 +128,10 @@ pub(crate) struct SharedContext<'tcx> {
 pub(crate)span_correspondence_map:FxHashMap<rustc_span::Span,LinkFromSrc>,
 /// The [`Cache`] used during rendering.
 pub(crate)cache:Cache,
-
 pub(crate)call_locations:AllCallLocations,
+/// Controls whether we read / write to cci files in the doc root. Defaults read=true,
+/// write=true
+should_merge:ShouldMerge,
 }
 
 implSharedContext<'_>{
@@ -551,6 +553,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
 span_correspondence_map: matches,
  cache,
  call_locations,
+should_merge: options.should_merge,
 };
 
 let dst = output;
@@ -640,92 +643,96 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
 );
  shared.fs.write(final_file, v)?;
 
-// Generating settings page.
- page.title = "Settings";
- page.description = "Settings of Rustdoc";
- page.root_path = "./";
- page.rust_logo = true;
+// if to avoid writing help, settings files to doc root unless we're on the final invocation
+if shared.should_merge.write_rendered_cci{
+// Generating settings page.
+ page.title = "Settings";
+ page.description = "Settings of Rustdoc";
+ page.root_path = "./";
+ page.rust_logo = true;
 
-let sidebar = "<h2 class=\"location\">Settings</h2><div class=\"sidebar-elems\"></div>";
-let v = layout::render(
-&shared.layout,
-&page,
- sidebar,
- |buf:&mutBuffer| {
-write!(
- buf,
-"<div class=\"main-heading\">\
- <h1>Rustdoc settings</h1>\
- <span class=\"out-of-band\">\
- <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\
- Back\
- </a>\
- </span>\
- </div>\
- <noscript>\
- <section>\
- You need to enable JavaScript be able to update your settings.\
- </section>\
- </noscript>\
- <script defer src=\"{static_root_path}{settings_js}\"></script>",
- static_root_path = page.get_static_root_path(),
- settings_js = static_files::STATIC_FILES.settings_js,
-);
-// Pre-load all theme CSS files, so that switching feels seamless.
-//
-// When loading settings.html as a popover, the equivalent HTML is
-// generated in main.js.
-for file in&shared.style_files{
-ifletOk(theme) = file.basename(){
-write!(
- buf,
-"<link rel=\"preload\" href=\"{root_path}{theme}{suffix}.css\"\
- as=\"style\">",
- root_path = page.static_root_path.unwrap_or(""),
- suffix = page.resource_suffix,
-);
+let sidebar = "<h2 class=\"location\">Settings</h2><div class=\"sidebar-elems\"></div>";
+let v = layout::render(
+&shared.layout,
+&page,
+ sidebar,
+ |buf:&mutBuffer| {
+write!(
+ buf,
+"<div class=\"main-heading\">\
+ <h1>Rustdoc settings</h1>\
+ <span class=\"out-of-band\">\
+ <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\
+ Back\
+ </a>\
+ </span>\
+ </div>\
+ <noscript>\
+ <section>\
+ You need to enable JavaScript be able to update your settings.\
+ </section>\
+ </noscript>\
+ <script defer src=\"{static_root_path}{settings_js}\"></script>",
+ static_root_path = page.get_static_root_path(),
+ settings_js = static_files::STATIC_FILES.settings_js,
+);
+// Pre-load all theme CSS files, so that switching feels seamless.
+//
+// When loading settings.html as a popover, the equivalent HTML is
+// generated in main.js.
+for file in&shared.style_files{
+ifletOk(theme) = file.basename(){
+write!(
+ buf,
+"<link rel=\"preload\" href=\"{root_path}{theme}{suffix}.css\"\
+ as=\"style\">",
+ root_path = page.static_root_path.unwrap_or(""),
+ suffix = page.resource_suffix,
+);
+}
 }
-}
-},
-&shared.style_files,
-);
- shared.fs.write(settings_file, v)?;
+},
+&shared.style_files,
+);
+ shared.fs.write(settings_file, v)?;
 
-// Generating help page.
- page.title = "Help";
- page.description = "Documentation for Rustdoc";
- page.root_path = "./";
- page.rust_logo = true;
+// Generating help page.
+page.title = "Help";
+page.description = "Documentation for Rustdoc";
+page.root_path = "./";
+page.rust_logo = true;
 
-let sidebar = "<h2 class=\"location\">Help</h2><div class=\"sidebar-elems\"></div>";
-let v = layout::render(
-&shared.layout,
-&page,
- sidebar,
- |buf:&mutBuffer| {
-write!(
- buf,
-"<div class=\"main-heading\">\
- <h1>Rustdoc help</h1>\
- <span class=\"out-of-band\">\
- <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\
- Back\
- </a>\
- </span>\
- </div>\
- <noscript>\
- <section>\
- <p>You need to enable JavaScript to use keyboard commands or search.</p>\
- <p>For more information, browse the <a href=\"https://doc.rust-lang.org/rustdoc/\">rustdoc handbook</a>.</p>\
- </section>\
- </noscript>",
-)
-},
-&shared.style_files,
-);
- shared.fs.write(help_file, v)?;
+let sidebar = "<h2 class=\"location\">Help</h2><div class=\"sidebar-elems\"></div>";
+let v = layout::render(
+&shared.layout,
+&page,
+ sidebar,
+ |buf:&mutBuffer| {
+write!(
+ buf,
+"<div class=\"main-heading\">\
+ <h1>Rustdoc help</h1>\
+ <span class=\"out-of-band\">\
+ <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\
+ Back\
+ </a>\
+ </span>\
+ </div>\
+ <noscript>\
+ <section>\
+ <p>You need to enable JavaScript to use keyboard commands or search.</p>\
+ <p>For more information, browse the <a href=\"https://doc.rust-lang.org/rustdoc/\">rustdoc handbook</a>.</p>\
+ </section>\
+ </noscript>",
+)
+},
+&shared.style_files,
+);
+ shared.fs.write(help_file, v)?;
+}
 
-if shared.layout.scrape_examples_extension{
+// if to avoid writing files to doc root unless we're on the final invocation
+if shared.layout.scrape_examples_extension && shared.should_merge.write_rendered_cci{
  page.title = "About scraped examples";
  page.description = "How the scraped examples feature works in Rustdoc";
 let v = layout::render(

src/librustdoc/html/render/mod.rs

@@ -61,6 +61,7 @@ use tracing::{debug, info};
 
 pub(crate)useself::context::*;
 pub(crate)useself::span_map::{collect_spans_and_sources,LinkFromSrc};
+pub(crate)useself::write_shared::*;
 usecrate::clean::{self,ItemId,RenderedLink};
 usecrate::error::Error;
 usecrate::formats::cache::Cache;