From e840c8e81c8832352db5aadb1a73c8f76e4bb469 Mon Sep 17 00:00:00 2001 From: Jade Date: Mon, 10 May 2021 03:36:12 -0700 Subject: [PATCH 1/5] 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. --- src/cargo/ops/cargo_doc.rs | 17 ++++++++++++++--- src/doc/src/reference/config.md | 15 +++++++++++++++ src/doc/src/reference/environment-variables.md | 3 ++- tests/testsuite/doc.rs | 14 ++++++++++++++ 4 files changed, 45 insertions(+), 4 deletions(-) diff --git a/src/cargo/ops/cargo_doc.rs b/src/cargo/ops/cargo_doc.rs index f9b2d843381..da0898ec583 100644 --- a/src/cargo/ops/cargo_doc.rs +++ b/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, +} + /// 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::("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) -> 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!( diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index ef5e7ab6bd8..fd0818e464f 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 +[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 diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 4fff3b0ec89..7172b3d70e0 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 [`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 diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs index 01b25612e5b..497b6b055f9 100644 --- a/tests/testsuite/doc.rs +++ b/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] From 6ea1eb3f7ed4924763cb96550711ce31f46886c9 Mon Sep 17 00:00:00 2001 From: Jade Date: Sat, 15 May 2021 13:23:55 -0700 Subject: [PATCH 2/5] Move browser setting to [doc], use PathAndArgs --- src/cargo/ops/cargo_doc.rs | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/src/cargo/ops/cargo_doc.rs b/src/cargo/ops/cargo_doc.rs index da0898ec583..baee6ceb5d8 100644 --- a/src/cargo/ops/cargo_doc.rs +++ b/src/cargo/ops/cargo_doc.rs @@ -1,13 +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 crate::{core::compiler::RustcTargetData, util::config::PathAndArgs}; use serde::Deserialize; -use std::collections::HashMap; -use std::ffi::OsString; use std::path::Path; use std::process::Command; +use std::{collections::HashMap, path::PathBuf}; /// Strongly typed options for the `cargo doc` command. #[derive(Debug)] @@ -22,7 +21,7 @@ pub struct DocOptions { struct CargoDocConfig { /// Browser to use to open docs. If this is unset, the value of the environment variable /// `BROWSER` will be used. - browser: Option, + browser: Option, } /// Main method for `cargo doc`. @@ -92,19 +91,31 @@ pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> { if path.exists() { let mut shell = ws.config().shell(); shell.status("Opening", path.display())?; - let cfg = ws.config().get::("cargo-doc")?; - open_docs(&path, &mut shell, cfg.browser.map(|v| v.into()))?; + 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, config_browser: Option) -> CargoResult<()> { - let browser = config_browser.or_else(|| std::env::var_os("BROWSER")); +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) => { - if let Err(e) = Command::new(&browser).arg(path).status() { + 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(), From ed46a9a4dec951d31b20f75bb179f6a346dbb377 Mon Sep 17 00:00:00 2001 From: Jade Date: Sat, 15 May 2021 14:21:13 -0700 Subject: [PATCH 3/5] test path and args --- src/cargo/ops/cargo_doc.rs | 5 ++--- tests/testsuite/doc.rs | 6 +++--- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/src/cargo/ops/cargo_doc.rs b/src/cargo/ops/cargo_doc.rs index baee6ceb5d8..6477a4d6f71 100644 --- a/src/cargo/ops/cargo_doc.rs +++ b/src/cargo/ops/cargo_doc.rs @@ -95,9 +95,8 @@ pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> { open_docs( &path, &mut shell, - cfg.browser.map(|path_args| { - (path_args.path.resolve_program(&ws.config()), path_args.args) - }), + cfg.browser + .map(|path_args| (path_args.path.resolve_program(ws.config()), path_args.args)), )?; } } diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs index 497b6b055f9..40357a8d212 100644 --- a/tests/testsuite/doc.rs +++ b/tests/testsuite/doc.rs @@ -1189,15 +1189,15 @@ fn doc_workspace_open_different_library_and_package_names() { p.change_file( ".cargo/config.toml", r#" - [cargo-doc] - browser = "echo" + [doc] + browser = ["echo", "a"] "#, ); // 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") + .with_stdout_contains("[..]a [CWD]/target/doc/foolib/index.html") .run(); } From 50486be0c0f12cbcf9674cb8053b9b892ada1b64 Mon Sep 17 00:00:00 2001 From: Jade Date: Sat, 15 May 2021 18:59:24 -0700 Subject: [PATCH 4/5] testsuite/doc: Check the arguments used to invoke the browser Previously we apparently weren't doing this as we weren't checking stdout. --- tests/testsuite/doc.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs index 40357a8d212..5b039446fa2 100644 --- a/tests/testsuite/doc.rs +++ b/tests/testsuite/doc.rs @@ -1184,6 +1184,7 @@ 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( @@ -1197,7 +1198,7 @@ fn doc_workspace_open_different_library_and_package_names() { // 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") + .with_stdout_contains("a [CWD]/target/doc/foolib/index.html") .run(); } From 6128b54b8aa817b68226245df90e87bf68baf330 Mon Sep 17 00:00:00 2001 From: Jade Date: Thu, 20 May 2021 22:52:49 -0700 Subject: [PATCH 5/5] docs: `cargo-doc.browser` -> `doc.browser`; mention in cargo-{rust,}doc.1 --- src/doc/man/cargo-doc.md | 4 +++- src/doc/man/cargo-rustdoc.md | 4 +++- src/doc/man/generated_txt/cargo-doc.txt | 4 +++- src/doc/man/generated_txt/cargo-rustdoc.txt | 4 +++- src/doc/src/commands/cargo-doc.md | 4 +++- src/doc/src/commands/cargo-rustdoc.md | 4 +++- src/doc/src/reference/config.md | 8 ++++---- src/doc/src/reference/environment-variables.md | 4 ++-- src/etc/man/cargo-doc.1 | 4 +++- src/etc/man/cargo-rustdoc.1 | 4 +++- 10 files changed, 30 insertions(+), 14 deletions(-) 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 fd0818e464f..af11bb80b71 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -67,7 +67,7 @@ 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] +[doc] browser = "chromium" # browser to use with `cargo doc --open`, # overrides the `BROWSER` environment variable @@ -400,11 +400,11 @@ directory. Controls whether or not build pipelining is used. This allows Cargo to schedule overlapping invocations of `rustc` in parallel when possible. -#### `[cargo-doc]` +#### `[doc]` -The `[cargo-doc]` table defines options for the [`cargo doc`] command. +The `[doc]` table defines options for the [`cargo doc`] command. -##### `cargo-doc.browser` +##### `doc.browser` This option sets the browser to be used by [`cargo doc`], overriding the `BROWSER` environment variable when opening documentation with the `--open` diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index 7172b3d70e0..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, see [`cargo-doc.browser`] for more details. + 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,7 +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 +[`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