Skip to content

Commit 05f1ded

Browse files
borsbors
committed
Auto merge of #3515 - sdroege:doc-all, r=alexcrichton
 Add support for documenting all members of the workspace with "doc --all" #3491
2 parents 46bba43 + b850c25 commit 05f1ded

File tree

3 files changed

+131
-16
lines changed

3 files changed

+131
-16
lines changed

‎src/bin/doc.rs

+12-1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ pub struct Options {
2323
flag_bin: Vec<String>,
2424
flag_frozen: bool,
2525
flag_locked: bool,
26+
flag_all: bool,
2627
}
2728

2829
pub const USAGE: &'static str = "
@@ -35,6 +36,7 @@ Options:
3536
-h, --help Print this message
3637
--open Opens the docs in a browser after the operation
3738
-p SPEC, --package SPEC ... Package to document
39+
--all Document all packages in the workspace
3840
--no-deps Don't build documentation for dependencies
3941
-j N, --jobs N Number of parallel jobs, defaults to # of CPUs
4042
--lib Document only this package's library
@@ -55,6 +57,9 @@ Options:
5557
By default the documentation for the local package and all dependencies is
5658
built. The output is all placed in `target/doc` in rustdoc's usual format.
5759
60+
All packages in the workspace are documented if the `--all` flag is supplied. The
61+
`--all` flag may be supplied in the presence of a virtual manifest.
62+
5863
If the --package argument is given, then SPEC is a package id specification
5964
which indicates which package should be documented. If it is not given, then the
6065
current package is documented. For more information on SPEC and its format, see
@@ -70,6 +75,12 @@ pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
7075

7176
let root = find_root_manifest_for_wd(options.flag_manifest_path, config.cwd())?;
7277

78+
let spec = if options.flag_all {
79+
Packages::All
80+
} else {
81+
Packages::Packages(&options.flag_package)
82+
};
83+
7384
let empty = Vec::new();
7485
let doc_opts = ops::DocOptions {
7586
open_result: options.flag_open,
@@ -80,7 +91,7 @@ pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
8091
features: &options.flag_features,
8192
all_features: options.flag_all_features,
8293
no_default_features: options.flag_no_default_features,
83-
spec: Packages::Packages(&options.flag_package),
94+
spec: spec,
8495
filter: ops::CompileFilter::new(options.flag_lib,
8596
&options.flag_bin,
8697
&empty,

‎src/cargo/ops/cargo_doc.rs

+21-15
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ use std::fs;
33
use std::path::Path;
44
use std::process::Command;
55

6-
use core::{PackageIdSpec, Workspace};
6+
use core::Workspace;
77
use ops;
88
use util::CargoResult;
99

@@ -13,20 +13,28 @@ pub struct DocOptions<'a> {
1313
}
1414

1515
pub fn doc(ws: &Workspace, options: &DocOptions) -> CargoResult<()> {
16-
let package = ws.current()?;
16+
let specs = options.compile_opts.spec.into_package_id_specs(ws)?;
17+
let resolve = ops::resolve_ws_precisely(ws,
18+
None,
19+
options.compile_opts.features,
20+
options.compile_opts.all_features,
21+
options.compile_opts.no_default_features,
22+
&specs)?;
23+
let (packages, resolve_with_overrides) = resolve;
1724

18-
let spec = match options.compile_opts.spec {
19-
ops::Packages::Packages(packages) => packages,
20-
_ => {
21-
// This should not happen, because the `doc` binary is hard-coded to pass
22-
// the `Packages::Packages` variant.
23-
bail!("`cargo doc` does not support the `--all` flag")
24-
},
25+
let mut pkgs = Vec::new();
26+
if specs.len() > 0 {
27+
for p in specs.iter() {
28+
pkgs.push(packages.get(p.query(resolve_with_overrides.iter())?)?);
29+
}
30+
} else {
31+
let root_package = ws.current()?;
32+
pkgs.push(root_package);
2533
};
2634

2735
let mut lib_names = HashSet::new();
2836
let mut bin_names = HashSet::new();
29-
if spec.is_empty() {
37+
for package in &pkgs {
3038
for target in package.targets().iter().filter(|t| t.documented()) {
3139
if target.is_lib() {
3240
assert!(lib_names.insert(target.crate_name()));
@@ -46,12 +54,10 @@ pub fn doc(ws: &Workspace, options: &DocOptions) -> CargoResult<()> {
4654
ops::compile(ws, &options.compile_opts)?;
4755

4856
if options.open_result {
49-
let name = if spec.len() > 1 {
57+
let name = if pkgs.len() > 1 {
5058
bail!("Passing multiple packages and `open` is not supported")
51-
} else if spec.len() == 1 {
52-
PackageIdSpec::parse(&spec[0])?
53-
.name()
54-
.replace("-", "_")
59+
} else if pkgs.len() == 1 {
60+
pkgs[0].name().replace("-", "_")
5561
} else {
5662
match lib_names.iter().chain(bin_names.iter()).nth(0) {
5763
Some(s) => s.to_string(),

‎tests/doc.rs

+98
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ use std::fs;
66

77
use cargotest::{is_nightly, rustc_host};
88
use cargotest::support::{project, execs, path2url};
9+
use cargotest::support::registry::Package;
910
use hamcrest::{assert_that, existing_file, existing_dir, is_not};
1011

1112
#[test]
@@ -612,3 +613,100 @@ fn plugins_no_use_target() {
612613
.arg("-v"),
613614
execs().with_status(0));
614615
}
616+
617+
#[test]
618+
fn doc_all_workspace() {
619+
let p = project("foo")
620+
.file("Cargo.toml", r#"
621+
[project]
622+
name = "foo"
623+
version = "0.1.0"
624+
625+
[dependencies]
626+
bar = { path = "bar" }
627+
628+
[workspace]
629+
"#)
630+
.file("src/main.rs", r#"
631+
fn main() {}
632+
"#)
633+
.file("bar/Cargo.toml", r#"
634+
[project]
635+
name = "bar"
636+
version = "0.1.0"
637+
"#)
638+
.file("bar/src/lib.rs", r#"
639+
pub fn bar() {}
640+
"#);
641+
p.build();
642+
643+
// The order in which bar is compiled or documented is not deterministic
644+
assert_that(p.cargo_process("doc")
645+
.arg("--all"),
646+
execs().with_status(0)
647+
.with_stderr_contains("[..] Documenting bar v0.1.0 ([..])")
648+
.with_stderr_contains("[..] Compiling bar v0.1.0 ([..])")
649+
.with_stderr_contains("[..] Documenting foo v0.1.0 ([..])"));
650+
}
651+
652+
#[test]
653+
fn doc_all_virtual_manifest() {
654+
let p = project("workspace")
655+
.file("Cargo.toml", r#"
656+
[workspace]
657+
members = ["foo", "bar"]
658+
"#)
659+
.file("foo/Cargo.toml", r#"
660+
[project]
661+
name = "foo"
662+
version = "0.1.0"
663+
"#)
664+
.file("foo/src/lib.rs", r#"
665+
pub fn foo() {}
666+
"#)
667+
.file("bar/Cargo.toml", r#"
668+
[project]
669+
name = "bar"
670+
version = "0.1.0"
671+
"#)
672+
.file("bar/src/lib.rs", r#"
673+
pub fn bar() {}
674+
"#);
675+
p.build();
676+
677+
// The order in which foo and bar are documented is not guaranteed
678+
assert_that(p.cargo_process("doc")
679+
.arg("--all"),
680+
execs().with_status(0)
681+
.with_stderr_contains("[..] Documenting bar v0.1.0 ([..])")
682+
.with_stderr_contains("[..] Documenting foo v0.1.0 ([..])"));
683+
}
684+
685+
#[test]
686+
fn doc_all_member_dependency_same_name() {
687+
let p = project("workspace")
688+
.file("Cargo.toml", r#"
689+
[workspace]
690+
members = ["a"]
691+
"#)
692+
.file("a/Cargo.toml", r#"
693+
[project]
694+
name = "a"
695+
version = "0.1.0"
696+
697+
[dependencies]
698+
a = "0.1.0"
699+
"#)
700+
.file("a/src/lib.rs", r#"
701+
pub fn a() {}
702+
"#);
703+
p.build();
704+
705+
Package::new("a", "0.1.0").publish();
706+
707+
assert_that(p.cargo_process("doc")
708+
.arg("--all"),
709+
execs().with_status(0)
710+
.with_stderr_contains("[..] Updating registry `[..]`")
711+
.with_stderr_contains("[..] Documenting a v0.1.0 ([..])"));
712+
}

0 commit comments

Comments
 (0)