Auto merge of #9473 - lf-:meow, r=ehuss

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: bors

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