diff --git a/src/cargo/ops/cargo_doc.rs b/src/cargo/ops/cargo_doc.rs index f9b2d843381..6477a4d6f71 100644 --- a/src/cargo/ops/cargo_doc.rs +++ b/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, +} + /// 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::("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)>, +) -> 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(), diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md index 20a9c2589d1..c97f13a0b83 100644 --- a/src/doc/man/cargo-doc.md +++ b/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`" }} diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md index 958aa13c217..af5d6906ae2 100644 --- a/src/doc/man/cargo-rustdoc.md +++ b/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}} diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 8798744e50b..b81160f4406 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/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 + + configuration option. --no-deps Do not build documentation for dependencies. diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 74c281554e7..d6161e79e2b 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/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 + + configuration option. Package Selection By default, the package in the current working directory is selected. diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 7640416f9e1..413f7f48c11 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -22,7 +22,9 @@ is placed in `target/doc` in rustdoc's usual format.
--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 configuration +option.
--no-deps
diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index cbd3db6e84e..b0b31cec6cc 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -38,7 +38,9 @@ or the `build.rustdocflags` [config value](../reference/config.html).
--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 configuration +option. diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index ef5e7ab6bd8..af11bb80b71 100644 --- a/src/doc/src/reference/config.md +++ b/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 diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 4fff3b0ec89..62625bc789a 100644 --- a/src/doc/src/reference/environment-variables.md +++ b/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 diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 36856d96868..cb700b2f870 100644 --- a/src/etc/man/cargo-doc.1 +++ b/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 configuration +option. .RE .sp \fB\-\-no\-deps\fR diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 2845cf9d632..7ff1b638da1 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -32,7 +32,9 @@ or the \fBbuild.rustdocflags\fR \fIconfig value\fR configuration +option. .RE .SS "Package Selection" By default, the package in the current working directory is selected. The \fB\-p\fR diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs index 01b25612e5b..5b039446fa2 100644 --- a/tests/testsuite/doc.rs +++ b/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(); }