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/man/cargo-doc.md

@@ -22,7 +22,9 @@ is placed in `target/doc` in rustdoc's usual format.
 
 {{#option "`--open`" }}
 Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the `BROWSER` environment variable.
+browser unless you define another one in the `BROWSER` environment variable
+or use the [`doc.browser`](../reference/config.html#docbrowser) configuration
+option.
 {{/option}}
 
 {{#option "`--no-deps`" }}

src/doc/man/cargo-rustdoc.md

@@ -34,7 +34,9 @@ or the `build.rustdocflags` [config value](../reference/config.html).
 
 {{#option "`--open`" }}
 Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the `BROWSER` environment variable.
+browser unless you define another one in the `BROWSER` environment variable
+or use the [`doc.browser`](../reference/config.html#docbrowser) configuration
+option.
 {{/option}}
 
 {{/options}}

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

@@ -15,7 +15,9 @@ OPTIONS
        --open
            Open the docs in a browser after building them. This will use your
            default browser unless you define another one in the BROWSER
-           environment variable.
+           environment variable or use the doc.browser
+           <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser>
+           configuration option.
 
        --no-deps
            Do not build documentation for dependencies.

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

@@ -34,7 +34,9 @@ OPTIONS
        --open
            Open the docs in a browser after building them. This will use your
            default browser unless you define another one in the BROWSER
-           environment variable.
+           environment variable or use the doc.browser
+           <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser>
+           configuration option.
 
    Package Selection
        By default, the package in the current working directory is selected.

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

@@ -22,7 +22,9 @@ is placed in `target/doc` in rustdoc's usual format.
 
 <dt class="option-term" id="option-cargo-doc---open"><a class="option-anchor" href="#option-cargo-doc---open"></a><code>--open</code></dt>
 <dd class="option-desc">Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the <code>BROWSER</code> environment variable.</dd>
+browser unless you define another one in the <code>BROWSER</code> environment variable
+or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration
+option.</dd>
 
 
 <dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt>

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

@@ -38,7 +38,9 @@ or the `build.rustdocflags` [config value](../reference/config.html).
 
 <dt class="option-term" id="option-cargo-rustdoc---open"><a class="option-anchor" href="#option-cargo-rustdoc---open"></a><code>--open</code></dt>
 <dd class="option-desc">Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the <code>BROWSER</code> environment variable.</dd>
+browser unless you define another one in the <code>BROWSER</code> environment variable
+or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration
+option.</dd>
 
 
 </dl>

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
 
+[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.
 
+#### `[doc]`
+
+The `[doc]` table defines options for the [`cargo doc`] command.
+
+##### `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 [`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
+[`doc.browser`]: config.md#docbrowser
 [`cargo-new.name`]: config.md#cargo-newname
 [`cargo-new.email`]: config.md#cargo-newemail
 [`cargo-new.vcs`]: config.md#cargo-newvcs

src/etc/man/cargo-doc.1

@@ -16,7 +16,9 @@ is placed in \fBtarget/doc\fR in rustdoc's usual format.
 \fB\-\-open\fR
 .RS 4
 Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the \fBBROWSER\fR environment variable.
+browser unless you define another one in the \fBBROWSER\fR environment variable
+or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration
+option.
 .RE
 .sp
 \fB\-\-no\-deps\fR

src/etc/man/cargo-rustdoc.1

@@ -32,7 +32,9 @@ or the \fBbuild.rustdocflags\fR \fIconfig value\fR <https://doc.rust\-lang.org/c
 \fB\-\-open\fR
 .RS 4
 Open the docs in a browser after building them. This will use your default
-browser unless you define another one in the \fBBROWSER\fR environment variable.
+browser unless you define another one in the \fBBROWSER\fR environment variable
+or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration
+option.
 .RE
 .SS "Package Selection"
 By default, the package in the current working directory is selected. The \fB\-p\fR

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();
 }