Add a cargo-doc.browser config option

The idea of this option is to allow cargo to use a separate browser from
the rest of the system. My motivation in doing this is that I want to
write a script that adds a symbolic link in some web root on my system
such that I can access my docs via the http protocol to avoid the
limitations of the file protocol that are accessibility problems for me.
For instance, zoom is not retained across multiple pages and Stylus
filters don't work well.

Author: lf-

src/cargo/ops/cargo_doc.rs

@@ -3,7 +3,9 @@ use crate::core::resolver::HasDevUnits;
 use crate::core::{Shell, Workspace};
 use crate::ops;
 use crate::util::CargoResult;
+use serde::Deserialize;
 use std::collections::HashMap;
+use std::ffi::OsString;
 use std::path::Path;
 use std::process::Command;
 
@@ -16,6 +18,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<String>,
+}
+
 /// 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,15 +92,17 @@ 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>("cargo-doc")?;
+            open_docs(&path, &mut shell, cfg.browser.map(|v| v.into()))?;
         }
     }
 
     Ok(())
 }
 
-fn open_docs(path: &Path, shell: &mut Shell) -> CargoResult<()> {
-    match std::env::var_os("BROWSER") {
+fn open_docs(path: &Path, shell: &mut Shell, config_browser: Option<OsString>) -> CargoResult<()> {
+    let browser = config_browser.or_else(|| std::env::var_os("BROWSER"));
+    match browser {
         Some(browser) => {
             if let Err(e) = Command::new(&browser).arg(path).status() {
                 shell.warn(format!(

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

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