Auto merge of #9808 - QiangHeisenberg:examples, r=ehuss

Adding the cargo doc --examples subcommand

Adding the cargo doc --examples subcommand

#4508

Author: bors

src/bin/cargo/commands/doc.rs

@@ -20,10 +20,12 @@ pub fn cli() -> App {
         .arg(opt("no-deps", "Don't build documentation for dependencies"))
         .arg(opt("document-private-items", "Document private items"))
         .arg_jobs()
-        .arg_targets_lib_bin(
+        .arg_targets_lib_bin_example(
             "Document only this package's library",
             "Document only the specified binary",
             "Document all binaries",
+            "Document only the specified example",
+            "Document all examples",
         )
         .arg_release("Build artifacts in release mode, with optimizations")
         .arg_profile("Build artifacts with the specified profile")

src/cargo/util/command_prelude.rs

@@ -87,20 +87,27 @@ pub trait AppExt: Sized {
         benches: &'static str,
         all: &'static str,
     ) -> Self {
-        self.arg_targets_lib_bin(lib, bin, bins)
-            ._arg(optional_multi_opt("example", "NAME", example))
-            ._arg(opt("examples", examples))
+        self.arg_targets_lib_bin_example(lib, bin, bins, example, examples)
             ._arg(optional_multi_opt("test", "NAME", test))
             ._arg(opt("tests", tests))
             ._arg(optional_multi_opt("bench", "NAME", bench))
             ._arg(opt("benches", benches))
             ._arg(opt("all-targets", all))
     }
 
-    fn arg_targets_lib_bin(self, lib: &'static str, bin: &'static str, bins: &'static str) -> Self {
+    fn arg_targets_lib_bin_example(
+        self,
+        lib: &'static str,
+        bin: &'static str,
+        bins: &'static str,
+        example: &'static str,
+        examples: &'static str,
+    ) -> Self {
         self._arg(opt("lib", lib))
             ._arg(optional_multi_opt("bin", "NAME", bin))
             ._arg(opt("bins", bins))
+            ._arg(optional_multi_opt("example", "NAME", example))
+            ._arg(opt("examples", examples))
     }
 
     fn arg_targets_bins_examples(

src/doc/man/cargo-doc.md

@@ -52,6 +52,16 @@ flag and will always document the given target.
 
 {{#options}}
 {{> options-targets-lib-bin }}
+
+{{#option "`--example` _name_..." }}
+{{actionverb}} the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.
+{{/option}}
+
+{{#option "`--examples`" }}
+{{actionverb}} all example targets.
+{{/option}}
+
 {{/options}}
 
 {{> section-features }}

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

@@ -82,6 +82,13 @@ OPTIONS
        --bins
            Document all binary targets.
 
+       --example name...
+           Document the specified example. This flag may be specified multiple
+           times and supports common Unix glob patterns.
+
+       --examples
+           Document all example targets.
+
    Feature Selection
        The feature flags allow you to control which features are enabled. When
        no feature options are given, the default feature is activated for every

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

@@ -107,6 +107,16 @@ and supports common Unix glob patterns.</dd>
 <dd class="option-desc">Document all binary targets.</dd>
 
 
+
+<dt class="option-term" id="option-cargo-doc---example"><a class="option-anchor" href="#option-cargo-doc---example"></a><code>--example</code> <em>name</em>...</dt>
+<dd class="option-desc">Document the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.</dd>
+
+
+<dt class="option-term" id="option-cargo-doc---examples"><a class="option-anchor" href="#option-cargo-doc---examples"></a><code>--examples</code></dt>
+<dd class="option-desc">Document all example targets.</dd>
+
+
 </dl>
 
 ### Feature Selection

src/etc/man/cargo-doc.1

@@ -95,6 +95,17 @@ and supports common Unix glob patterns.
 .RS 4
 Document all binary targets.
 .RE
+.sp
+\fB\-\-example\fR \fIname\fR\&...
+.RS 4
+Document the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.
+.RE
+.sp
+\fB\-\-examples\fR
+.RS 4
+Document all example targets.
+.RE
 .SS "Feature Selection"
 The feature flags allow you to control which features are enabled. When no
 feature options are given, the \fBdefault\fR feature is activated for every

tests/testsuite/doc.rs

@@ -513,6 +513,108 @@ fn doc_lib_bin_same_name_documents_bins_when_requested() {
     assert!(doc_html.contains("Binary"));
 }
 
+#[cargo_test]
+fn doc_lib_bin_example_same_name_documents_named_example_when_requested() {
+    let p = project()
+        .file(
+            "src/main.rs",
+            r#"
+                //! Binary documentation
+                extern crate foo;
+                fn main() {
+                    foo::foo();
+                }
+            "#,
+        )
+        .file(
+            "src/lib.rs",
+            r#"
+                //! Library documentation
+                pub fn foo() {}
+            "#,
+        )
+        .file(
+            "examples/ex1.rs",
+            r#"
+                //! Example1 documentation
+                pub fn x() { f(); }
+            "#,
+        )
+        .build();
+
+    p.cargo("doc --example ex1")
+        .with_stderr(
+            "\
+[CHECKING] foo v0.0.1 ([CWD])
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
+        )
+        .run();
+
+    let doc_html = p.read_file("target/doc/ex1/index.html");
+    assert!(!doc_html.contains("Library"));
+    assert!(!doc_html.contains("Binary"));
+    assert!(doc_html.contains("Example1"));
+}
+
+#[cargo_test]
+fn doc_lib_bin_example_same_name_documents_examples_when_requested() {
+    let p = project()
+        .file(
+            "src/main.rs",
+            r#"
+                //! Binary documentation
+                extern crate foo;
+                fn main() {
+                    foo::foo();
+                }
+            "#,
+        )
+        .file(
+            "src/lib.rs",
+            r#"
+                //! Library documentation
+                pub fn foo() {}
+            "#,
+        )
+        .file(
+            "examples/ex1.rs",
+            r#"
+                //! Example1 documentation
+                pub fn example1() { f(); }
+            "#,
+        )
+        .file(
+            "examples/ex2.rs",
+            r#"
+                //! Example2 documentation
+                pub fn example2() { f(); }
+            "#,
+        )
+        .build();
+
+    p.cargo("doc --examples")
+        .with_stderr(
+            "\
+[CHECKING] foo v0.0.1 ([CWD])
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
+        )
+        .run();
+
+    let example_doc_html_1 = p.read_file("target/doc/ex1/index.html");
+    let example_doc_html_2 = p.read_file("target/doc/ex2/index.html");
+
+    assert!(!example_doc_html_1.contains("Library"));
+    assert!(!example_doc_html_1.contains("Binary"));
+
+    assert!(!example_doc_html_2.contains("Library"));
+    assert!(!example_doc_html_2.contains("Binary"));
+
+    assert!(example_doc_html_1.contains("Example1"));
+    assert!(example_doc_html_2.contains("Example2"));
+}
+
 #[cargo_test]
 fn doc_dash_p() {
     let p = project()