Add scrape examples help page

5 files changed, 41 insertions, 7 deletions

diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css
index 55a11652c23..e3c3d614f01 100644
--- a/src/librustdoc/html/static/css/rustdoc.css
+++ b/src/librustdoc/html/static/css/rustdoc.css
@@ -2034,7 +2034,7 @@ details.rustdoc-toggle[open] > summary.hideme::after {
 
 /* Begin: styles for --scrape-examples feature */
 
-.scraped-example-list .section-header .scrape-help {
+.scraped-example-list .scrape-help {
 	margin-left: 10px;
 	padding: 0 4px;
 	font-weight: normal;
diff --git a/src/librustdoc/html/static/css/themes/ayu.css b/src/librustdoc/html/static/css/themes/ayu.css
index e073057528c..b1bf06c1865 100644
--- a/src/librustdoc/html/static/css/themes/ayu.css
+++ b/src/librustdoc/html/static/css/themes/ayu.css
@@ -612,11 +612,11 @@ input:checked + .slider {
 }
 
 
-.scraped-example-list .section-header .scrape-help {
+.scraped-example-list .scrape-help {
 	border-color: #aaa;
 	color: #eee;
 }
-.scraped-example-list .section-header .scrape-help:hover {
+.scraped-example-list .scrape-help:hover {
 	border-color: white;
 	color: white;
 }
diff --git a/src/librustdoc/html/static/css/themes/dark.css b/src/librustdoc/html/static/css/themes/dark.css
index a10029b6371..236304ccc9f 100644
--- a/src/librustdoc/html/static/css/themes/dark.css
+++ b/src/librustdoc/html/static/css/themes/dark.css
@@ -478,11 +478,11 @@ div.files > .selected {
 	border-bottom-color: #ddd;
 }
 
-.scraped-example-list .section-header .scrape-help {
+.scraped-example-list .scrape-help {
 	border-color: #aaa;
 	color: #eee;
 }
-.scraped-example-list .section-header .scrape-help:hover {
+.scraped-example-list .scrape-help:hover {
 	border-color: white;
 	color: white;
 }
diff --git a/src/librustdoc/html/static/css/themes/light.css b/src/librustdoc/html/static/css/themes/light.css
index a30dcac66db..c923902aba2 100644
--- a/src/librustdoc/html/static/css/themes/light.css
+++ b/src/librustdoc/html/static/css/themes/light.css
@@ -463,11 +463,11 @@ div.files > .selected {
 	border-bottom-color: #D5D5D5;
 }
 
-.scraped-example-list .section-header .scrape-help {
+.scraped-example-list .scrape-help {
 	border-color: #555;
 	color: #333;
 }
-.scraped-example-list .section-header .scrape-help:hover {
+.scraped-example-list .scrape-help:hover {
 	border-color: black;
 	color: black;
 }
diff --git a/src/librustdoc/html/static/scrape-examples-help.md b/src/librustdoc/html/static/scrape-examples-help.md
new file mode 100644
index 00000000000..035b2e18b00
--- /dev/null
+++ b/src/librustdoc/html/static/scrape-examples-help.md
@@ -0,0 +1,34 @@
+Rustdoc will automatically scrape examples of documented items from the `examples/` directory of a project. These examples will be included within the generated documentation for that item. For example, if your library contains a public function:
+
+```rust
+// src/lib.rs
+pub fn a_func() {}
+```
+
+And you have an example calling this function:
+
+```rust
+// examples/ex.rs
+fn main() {
+  a_crate::a_func();
+}
+```
+
+Then this code snippet will be included in the documentation for `a_func`.
+
+## How to read scraped examples
+
+Scraped examples are shown as blocks of code from a given file. The relevant item will be highlighted. If the file is larger than a couple lines, only a small window will be shown which you can expand by clicking ↕ in the top-right. If a file contains multiple instances of an item, you can use the ≺ and ≻ buttons to toggle through each instance.
+
+If there is more than one file that contains examples, then you should click "More examples" to see these examples.
+
+
+## How Rustdoc scrapes examples
+
+When you run `cargo doc`, Rustdoc will analyze all the crates that match Cargo's `--examples` filter for instances of items that occur in the crates being documented. Then Rustdoc will include the source code of these instances in the generated documentation.
+
+Rustdoc has a few techniques to ensure this doesn't overwhelm documentation readers, and that it doesn't blow up the page size:
+
+1. For a given item, a maximum of 5 examples are included in the page. The remaining examples are just links to source code.
+2. Only one example is shown by default, and the remaining examples are hidden behind a toggle.
+3. For a given file that contains examples, only the item containing the examples will be included in the generated documentation.