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

This commit 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,7 @@ 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 +49,28 @@ 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 mut target_args = values(args, "args");
+    let output_format = args.output_format()?;
+    if output_format.eq(&OutputFormat::Json) {
+        if config.cli_unstable().unstable_options {
+            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/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,7 @@ 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 +52,26 @@ 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) {
+        if config.cli_unstable().unstable_options {
+            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}}