Add a doc.browser config option

src/cargo/ops/cargo_doc.rs

@@ -1,11 +1,12 @@
-use crate::core::compiler::RustcTargetData;
 use crate::core::resolver::HasDevUnits;
 use crate::core::{Shell, Workspace};
 use crate::ops;
 use crate::util::CargoResult;
-use std::collections::HashMap;
+use crate::{core::compiler::RustcTargetData, util::config::PathAndArgs};
+use serde::Deserialize;
 use std::path::Path;
 use std::process::Command;
+use std::{collections::HashMap, path::PathBuf};
 
 /// Strongly typed options for the `cargo doc` command.
 #[derive(Debug)]
@@ -16,6 +17,13 @@ pub struct DocOptions {
     pub compile_opts: ops::CompileOptions,
 }
 
+#[derive(Deserialize)]
+struct CargoDocConfig {
+    /// Browser to use to open docs. If this is unset, the value of the environment variable
+    /// `BROWSER` will be used.
+    browser: Option<PathAndArgs>,
+}
+
 /// Main method for `cargo doc`.
 pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> {
     let specs = options.compile_opts.spec.to_package_id_specs(ws)?;
@@ -83,17 +91,30 @@ pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> {
         if path.exists() {
             let mut shell = ws.config().shell();
             shell.status("Opening", path.display())?;
-            open_docs(&path, &mut shell)?;
+            let cfg = ws.config().get::<CargoDocConfig>("doc")?;
+            open_docs(
+                &path,
+                &mut shell,
+                cfg.browser
+                    .map(|path_args| (path_args.path.resolve_program(ws.config()), path_args.args)),
+            )?;
         }
     }
 
     Ok(())
 }
 
-fn open_docs(path: &Path, shell: &mut Shell) -> CargoResult<()> {
-    match std::env::var_os("BROWSER") {
-        Some(browser) => {
-            if let Err(e) = Command::new(&browser).arg(path).status() {
+fn open_docs(
+    path: &Path,
+    shell: &mut Shell,
+    config_browser: Option<(PathBuf, Vec<String>)>,
+) -> CargoResult<()> {
+    let browser =
+        config_browser.or_else(|| Some((PathBuf::from(std::env::var_os("BROWSER")?), Vec::new())));
+
+    match browser {
+        Some((browser, initial_args)) => {
+            if let Err(e) = Command::new(&browser).args(initial_args).arg(path).status() {
                 shell.warn(format!(
                     "Couldn't open docs with {}: {}",
                     browser.to_string_lossy(),

src/doc/src/reference/config.md

@@ -67,6 +67,10 @@ incremental = true            # whether or not to enable incremental compilation
 dep-info-basedir = "…"        # path for the base directory for targets in depfiles
 pipelining = true             # rustc pipelining
 
+[cargo-doc]
+browser = "chromium"          # browser to use with `cargo doc --open`,
+                              # overrides the `BROWSER` environment variable
+
 [cargo-new]
 vcs = "none"              # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none')
 
@@ -396,6 +400,16 @@ directory.
 Controls whether or not build pipelining is used. This allows Cargo to
 schedule overlapping invocations of `rustc` in parallel when possible.
 
+#### `[cargo-doc]`
+
+The `[cargo-doc]` table defines options for the [`cargo doc`] command.
+
+##### `cargo-doc.browser`
+
+This option sets the browser to be used by [`cargo doc`], overriding the
+`BROWSER` environment variable when opening documentation with the `--open`
+option.
+
 #### `[cargo-new]`
 
 The `[cargo-new]` table defines defaults for the [`cargo new`] command.
@@ -928,6 +942,7 @@ Sets the width for progress bar.
 
 [`cargo bench`]: ../commands/cargo-bench.md
 [`cargo login`]: ../commands/cargo-login.md
+[`cargo doc`]: ../commands/cargo-doc.md
 [`cargo new`]: ../commands/cargo-new.md
 [`cargo publish`]: ../commands/cargo-publish.md
 [`cargo run`]: ../commands/cargo-run.md

src/doc/src/reference/environment-variables.md

@@ -52,7 +52,7 @@ system:
   detail.
 * `TERM` — If this is set to `dumb`, it disables the progress bar.
 * `BROWSER` — The web browser to execute to open documentation with [`cargo
-  doc`]'s' `--open` flag.
+  doc`]'s' `--open` flag, see [`cargo-doc.browser`] for more details.
 * `RUSTFMT` — Instead of running `rustfmt`,
   [`cargo fmt`](https://github.com/rust-lang/rustfmt) will execute this specified
   `rustfmt` instance instead.
@@ -134,6 +134,7 @@ supported environment variables are:
 [`build.incremental`]: config.md#buildincremental
 [`build.dep-info-basedir`]: config.md#builddep-info-basedir
 [`build.pipelining`]: config.md#buildpipelining
+[`cargo-doc.browser`]: config.md#cargo-docbrowser
 [`cargo-new.name`]: config.md#cargo-newname
 [`cargo-new.email`]: config.md#cargo-newemail
 [`cargo-new.vcs`]: config.md#cargo-newvcs

tests/testsuite/doc.rs

@@ -1184,6 +1184,21 @@ fn doc_workspace_open_different_library_and_package_names() {
         .env("BROWSER", "echo")
         .with_stderr_contains("[..] Documenting foo v0.1.0 ([..])")
         .with_stderr_contains("[..] [CWD]/target/doc/foolib/index.html")
+        .with_stdout_contains("[CWD]/target/doc/foolib/index.html")
+        .run();
+
+    p.change_file(
+        ".cargo/config.toml",
+        r#"
+        [doc]
+        browser = ["echo", "a"]
+    "#,
+    );
+
+    // check that the cargo config overrides the browser env var
+    p.cargo("doc --open")
+        .env("BROWSER", "true")
+        .with_stdout_contains("a [CWD]/target/doc/foolib/index.html")
         .run();
 }