rustdoc: auto create output directory when "--output-format json"

[tomkris]

This PR allows rustdoc to automatically create output directory in case it does not exist (when run with --output-format json).

This fixes rustdoc crash:

$ rustdoc --output-format json -Z unstable-options src/main.rs
error: couldn't generate documentation: No such file or directory (os error 2)
  |
  = note: failed to create or modify "doc/main.json"

error: aborting due to previous error

With this fix behavior of rustdoc --output-format json becomes consistent with rustdoc --output-format html (which already auto-creates output directory if it's missing)

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @jsha (or someone else) soon.

Please see the contribution instructions for more information.

[jsha]

This looks great. Thank you for the contribution!

I notice in the version of this code for the HTML docs, we keep a cache of what directories have been created. If this turns out to be a significant slowdown we might want to do the same thing here too; but I don't think that's a blocker.

rust/src/librustdoc/html/render/context.rs

Lines 130 to 137 in 237949b

	crate fn ensure_dir(&self, dst: &Path) -> Result<(), Error> {
	let mut dirs = self.created_dirs.borrow_mut();
	if !dirs.contains(dst) {
	try_err!(self.fs.create_dir_all(dst), dst);
	dirs.insert(dst.to_path_buf());
	}
	Ok(())

[jsha]

This can be simplified with the try_err macro. You'll also need to import PathError:

diff --git a/src/librustdoc/json/mod.rs b/src/librustdoc/json/mod.rs
index 6fadf72f54d..12281e78ffc 100644
--- a/src/librustdoc/json/mod.rs
+++ b/src/librustdoc/json/mod.rs
@@ -18,13 +18,14 @@
 
 use rustdoc_json_types as types;
 
-use crate::clean;
 use crate::clean::types::{ExternalCrate, ExternalLocation};
 use crate::config::RenderOptions;
+use crate::docfs::PathError;
 use crate::error::Error;
 use crate::formats::cache::Cache;
 use crate::formats::FormatRenderer;
 use crate::json::conversions::{from_item_id, IntoWithTcx};
+use crate::{clean, try_err};
 
 #[derive(Clone)]
 crate struct JsonRenderer<'tcx> {
@@ -257,8 +258,7 @@ fn after_krate(&mut self) -> Result<(), Error> {
             format_version: types::FORMAT_VERSION,
         };
         let out_dir = self.out_path.clone();
-        create_dir_all(&out_dir)
-            .map_err(|error| Error { error: error.to_string(), file: out_dir.clone() })?;
+        try_err!(create_dir_all(&out_dir), out_dir);
 
         let mut p = out_dir;
         p.push(output.index.get(&output.root).unwrap().name.clone().unwrap());

[tomkris]

Thanks for the suggestion Jacob, I included it into the PR.

I added new commit on top of original one. Please let me know if that's fine or if you want me to amend original commit instead (I did not find what's rust repo policy on commit append/amend on PRs).

[tomkris]

I notice in the version of this code for the HTML docs, we keep a cache of what directories have been created. If this turns out to be a significant slowdown we might want to do the same thing here too; but I don't think that's a blocker.

I may be wrong, my understanding that rustdoc --output-format json generates single json file per run (unlike rustdoc --output-format html which can generate thousands of html files and directories), and this code will run only once.

Are there cases where rustdoc will be generating multiple json files where this optimization will be beneficial?

[jsha]

my understanding that rustdoc --output-format json generates single json file per run (unlike rustdoc --output-format html which can generate thousands of html files and directories), and this code will run only once.

Aha, that makes sense. Thanks for pointing it out. I'm new to this part of the codebase.

The policy regarding squashes and merges is here: https://rustc-dev-guide.rust-lang.org/git.html#no-merge-policy.

The short version is: multiple commits are fine; squashing into a single commit is fine; the only thing that's not fine is having merge commits in your PR. And generally if you have tiny commits that aren't meaningful on their own, you're better off squashing them onto the previous one.

[jsha]

@bors r+ rollup

[bors]

📌 Commit 4e17170 has been approved by jsha