Add unstable "--output-format" option to "doc" & "rustdoc"

This commits enables the mimicking of "--output-format" option of
"rustdoc".

We achieved this by:
   * Handle "--output-format" arguments, accepts "html" or "json".
   * If "--ouput-format=json" we append the following to
     compile_opts.target_rustc_args:
     	1. "-Zunstable-commands"
	2.  "--output-format

Author: charmitro

src/bin/cargo/commands/doc.rs

@@ -1,6 +1,6 @@
 use crate::command_prelude::*;
 
-use cargo::ops::{self, DocOptions};
+use cargo::ops::{self, DocOptions, OutputFormat};
 
 pub fn cli() -> Command {
     subcommand("doc")
@@ -35,6 +35,13 @@ pub fn cli() -> Command {
         .arg_features()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
+        .arg(
+            opt(
+                "output-format",
+                "the output type to write (unstable)",
+            )
+            .value_name("PATH"),
+        )
         .arg_manifest_path()
         .arg_message_format()
         .arg_ignore_rust_version()
@@ -48,12 +55,21 @@ pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {
     let mode = CompileMode::Doc {
         deps: !args.flag("no-deps"),
     };
+
     let mut compile_opts =
         args.compile_options(config, mode, Some(&ws), ProfileChecking::Custom)?;
     compile_opts.rustdoc_document_private_items = args.flag("document-private-items");
+    let output_format = args.output_format()?;
+    if output_format.eq(&OutputFormat::Json) {
+        compile_opts.target_rustc_args = Some(vec![
+            "-Zunstable-options".to_string(),
+            "--output-format=json".to_string(),
+        ]);
+    }
 
     let doc_opts = DocOptions {
         open_result: args.flag("open"),
+        output_format,
         compile_opts,
     };
     ops::doc(&ws, &doc_opts)?;

src/bin/cargo/commands/rustdoc.rs

@@ -1,4 +1,4 @@
-use cargo::ops::{self, DocOptions};
+use cargo::ops::{self, DocOptions, OutputFormat};
 
 use crate::command_prelude::*;
 
@@ -35,6 +35,13 @@ pub fn cli() -> Command {
         .arg_features()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
+        .arg(
+            opt(
+                "output-format",
+                "the output type to write (unstable)",
+            )
+            .value_name("PATH"),
+        )
         .arg_manifest_path()
         .arg_message_format()
         .arg_unit_graph()
@@ -51,14 +58,23 @@ pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {
         Some(&ws),
         ProfileChecking::Custom,
     )?;
-    let target_args = values(args, "args");
+    let mut target_args = values(args, "args");
+
+    let output_format = args.output_format()?;
+    if output_format.eq(&OutputFormat::Json) {
+        target_args.push("-Zunstable-options".to_string());
+        target_args.push("--output-format=json".to_string());
+    }
+
     compile_opts.target_rustdoc_args = if target_args.is_empty() {
         None
     } else {
         Some(target_args)
     };
+
     let doc_opts = DocOptions {
         open_result: args.flag("open"),
+        output_format,
         compile_opts,
     };
     ops::doc(&ws, &doc_opts)?;

src/cargo/ops/cargo_doc.rs

@@ -6,20 +6,33 @@ use std::path::Path;
 use std::path::PathBuf;
 use std::process::Command;
 
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq)]
+pub enum OutputFormat {
+    #[default]
+    Html,
+    Json,
+}
+
 /// Strongly typed options for the `cargo doc` command.
 #[derive(Debug)]
 pub struct DocOptions {
     /// Whether to attempt to open the browser after compiling the docs
     pub open_result: bool,
+    /// Same as `rustdoc --output-format`
+    pub output_format: OutputFormat,
     /// Options to pass through to the compiler
     pub compile_opts: ops::CompileOptions,
 }
 
 /// Main method for `cargo doc`.
 pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> {
+    if options.open_result && options.output_format.eq(&OutputFormat::Json) {
+        anyhow::bail!("\"--open\" is not allowed with \"json\" output format.");
+    }
+
     let compilation = ops::compile(ws, &options.compile_opts)?;
 
-    if options.open_result {
+    if options.open_result && options.output_format.eq(&OutputFormat::Html) {
         let name = &compilation
             .root_crate_names
             .get(0)

src/cargo/ops/mod.rs

@@ -5,7 +5,7 @@ pub use self::cargo_compile::{
     compile, compile_with_exec, compile_ws, create_bcx, print, resolve_all_features, CompileOptions,
 };
 pub use self::cargo_compile::{CompileFilter, FilterRule, LibRule, Packages};
-pub use self::cargo_doc::{doc, DocOptions};
+pub use self::cargo_doc::{doc, DocOptions, OutputFormat};
 pub use self::cargo_fetch::{fetch, FetchOptions};
 pub use self::cargo_generate_lockfile::generate_lockfile;
 pub use self::cargo_generate_lockfile::update_lockfile;

src/cargo/util/command_prelude.rs

@@ -1,7 +1,9 @@
 use crate::core::compiler::{BuildConfig, MessageFormat, TimingOutput};
 use crate::core::resolver::CliFeatures;
 use crate::core::{Edition, Workspace};
-use crate::ops::{CompileFilter, CompileOptions, NewOptions, Packages, VersionControl};
+use crate::ops::{
+    CompileFilter, CompileOptions, NewOptions, OutputFormat, Packages, VersionControl,
+};
 use crate::util::important_paths::find_root_manifest_for_wd;
 use crate::util::interning::InternedString;
 use crate::util::restricted_names::is_glob_pattern;
@@ -366,6 +368,21 @@ pub trait ArgMatchesExt {
         Ok(ws)
     }
 
+    fn output_format(&self) -> CargoResult<OutputFormat> {
+        let arg: OutputFormat = match self._value_of("output-format") {
+            None => OutputFormat::default(),
+            Some(arg) => match arg {
+                "html" => OutputFormat::Html,
+                "json" => OutputFormat::Json,
+                _ => anyhow::bail!(
+                    "Allowed values are for \"--output-format\" are \"html\" or \"json\""
+                ),
+            },
+        };
+
+        Ok(arg)
+    }
+
     fn jobs(&self) -> CargoResult<Option<JobsConfig>> {
         let arg = match self._value_of("jobs") {
             None => None,

src/doc/man/cargo-doc.md

@@ -112,6 +112,7 @@ and supports common Unix glob patterns.
 {{#options}}
 {{> options-jobs }}
 {{> options-keep-going }}
+{{> options-output-format }}
 {{/options}}
 
 {{> section-environment }}

src/doc/man/cargo-rustdoc.md

@@ -100,6 +100,7 @@ if its name is the same as the lib target. Binaries are skipped if they have
 {{#options}}
 {{> options-jobs }}
 {{> options-keep-going }}
+{{> options-output-format }}
 {{/options}}
 
 {{> section-environment }}

src/doc/man/generated_txt/cargo-doc.txt

@@ -305,6 +305,9 @@ OPTIONS
            than aborting the build on the first one that fails to build.
            Unstable, requires -Zunstable-options.
 
+       --output-format
+           The output type to write. Unstable, requires -Zunstable-options.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

src/doc/man/generated_txt/cargo-rustdoc.txt

@@ -321,6 +321,9 @@ OPTIONS
            than aborting the build on the first one that fails to build.
            Unstable, requires -Zunstable-options.
 
+       --output-format
+           The output type to write. Unstable, requires -Zunstable-options.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

src/doc/man/includes/options-output-format.md

@@ -0,0 +1,4 @@
+{{#option "`--output-format`"}}
+The output type to write.
+Unstable, requires `-Zunstable-options`.
+{{/option}}

src/doc/src/commands/cargo-doc.md

@@ -368,6 +368,11 @@ the build on the first one that fails to build. Unstable, requires
 <code>-Zunstable-options</code>.</dd>
 
 
+<dt class="option-term" id="option-cargo-doc---output-format"><a class="option-anchor" href="#option-cargo-doc---output-format"></a><code>--output-format</code></dt>
+<dd class="option-desc">The output type to write.
+Unstable, requires <code>-Zunstable-options</code>.</dd>
+
+
 </dl>
 
 ## ENVIRONMENT

src/doc/src/commands/cargo-rustdoc.md

@@ -387,6 +387,11 @@ the build on the first one that fails to build. Unstable, requires
 <code>-Zunstable-options</code>.</dd>
 
 
+<dt class="option-term" id="option-cargo-rustdoc---output-format"><a class="option-anchor" href="#option-cargo-rustdoc---output-format"></a><code>--output-format</code></dt>
+<dd class="option-desc">The output type to write.
+Unstable, requires <code>-Zunstable-options</code>.</dd>
+
+
 </dl>
 
 ## ENVIRONMENT

src/etc/man/cargo-doc.1

@@ -371,6 +371,12 @@ Build as many crates in the dependency graph as possible, rather than aborting
 the build on the first one that fails to build. Unstable, requires
 \fB\-Zunstable\-options\fR\&.
 .RE
+.sp
+\fB\-\-output\-format\fR
+.RS 4
+The output type to write.
+Unstable, requires \fB\-Zunstable\-options\fR\&.
+.RE
 .SH "ENVIRONMENT"
 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 details on environment variables that Cargo reads.

src/etc/man/cargo-rustdoc.1

@@ -390,6 +390,12 @@ Build as many crates in the dependency graph as possible, rather than aborting
 the build on the first one that fails to build. Unstable, requires
 \fB\-Zunstable\-options\fR\&.
 .RE
+.sp
+\fB\-\-output\-format\fR
+.RS 4
+The output type to write.
+Unstable, requires \fB\-Zunstable\-options\fR\&.
+.RE
 .SH "ENVIRONMENT"
 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 details on environment variables that Cargo reads.

tests/testsuite/doc.rs

@@ -38,6 +38,36 @@ fn simple() {
     assert!(p.root().join("target/doc/foo/index.html").is_file());
 }
 
+#[cargo_test(nightly, reason = "--output-format is unstable")]
+fn simple_json() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                version = "0.0.1"
+                authors = []
+                build = "build.rs"
+            "#,
+        )
+        .file("build.rs", "fn main() {}")
+        .file("src/lib.rs", "pub fn foo() {}")
+        .build();
+
+    p.cargo("doc --output-format json")
+        .with_stderr(
+            "\
+[..] foo v0.0.1 ([CWD])
+[..] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]
+",
+        )
+        .run();
+    assert!(p.root().join("target/doc").is_dir());
+    assert!(p.root().join("target/doc/foo.json").is_file());
+}
+
 #[cargo_test]
 fn doc_no_libs() {
     let p = project()

tests/testsuite/rustdoc.rs

@@ -20,6 +20,24 @@ fn rustdoc_simple() {
         .run();
 }
 
+#[cargo_test(nightly, reason = "--output-format is unstable")]
+fn rustdoc_simple_json() {
+    let p = project().file("src/lib.rs", "").build();
+
+    p.cargo("rustdoc --output-format json -v")
+        .with_stderr(
+            "\
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[RUNNING] `rustdoc [..]--crate-name foo src/lib.rs [..]\
+        -o [CWD]/target/doc \
+        [..] \
+        -L dependency=[CWD]/target/debug/deps [..]`
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]
+",
+        )
+        .run();
+}
+
 #[cargo_test]
 fn rustdoc_args() {
     let p = project().file("src/lib.rs", "").build();