Add scrape examples help page

Author: willcrichton

src/librustdoc/html/render/context.rs

@@ -17,8 +17,8 @@ use super::print_item::{full_path, item_path, print_item};
 use super::search_index::build_index;
 use super::write_shared::write_shared;
 use super::{
-    collect_spans_and_sources, print_sidebar, settings, AllTypes, LinkFromSrc, NameDoc, StylePath,
-    BASIC_KEYWORDS,
+    collect_spans_and_sources, print_sidebar, scrape_examples_help, settings, AllTypes,
+    LinkFromSrc, NameDoc, StylePath, BASIC_KEYWORDS,
 };
 
 use crate::clean::{self, types::ExternalLocation, ExternalCrate};
@@ -551,6 +551,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
         let crate_name = self.tcx().crate_name(LOCAL_CRATE);
         let final_file = self.dst.join(crate_name.as_str()).join("all.html");
         let settings_file = self.dst.join("settings.html");
+        let scrape_examples_help_file = self.dst.join("scrape-examples-help.html");
 
         let mut root_path = self.dst.to_str().expect("invalid path").to_owned();
         if !root_path.ends_with('/') {
@@ -606,6 +607,20 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
             &self.shared.style_files,
         );
         self.shared.fs.write(settings_file, v)?;
+
+        if self.shared.layout.scrape_examples_extension {
+            page.title = "About scraped examples";
+            page.description = "How the scraped examples feature works in Rustdoc";
+            let v = layout::render(
+                &self.shared.layout,
+                &page,
+                "",
+                scrape_examples_help(&*self.shared),
+                &self.shared.style_files,
+            );
+            self.shared.fs.write(scrape_examples_help_file, v)?;
+        }
+
         if let Some(ref redirections) = self.shared.redirections {
             if !redirections.borrow().is_empty() {
                 let redirect_map_path =

src/librustdoc/html/render/mod.rs

@@ -62,7 +62,6 @@ use rustc_span::{
 use serde::ser::SerializeSeq;
 use serde::{Serialize, Serializer};
 
-use crate::clean::utils::DOC_RUST_LANG_ORG_CHANNEL;
 use crate::clean::{self, ItemId, RenderedLink, SelfTy};
 use crate::error::Error;
 use crate::formats::cache::Cache;
@@ -77,6 +76,7 @@ use crate::html::format::{
 use crate::html::highlight;
 use crate::html::markdown::{HeadingOffset, IdMap, Markdown, MarkdownHtml, MarkdownSummaryLine};
 use crate::html::sources;
+use crate::html::static_files::SCRAPE_EXAMPLES_HELP_MD;
 use crate::scrape_examples::{CallData, CallLocation};
 use crate::try_none;
 
@@ -462,6 +462,29 @@ fn settings(root_path: &str, suffix: &str, theme_names: Vec<String>) -> Result<S
     ))
 }
 
+fn scrape_examples_help(shared: &SharedContext<'_>) -> String {
+    let content = SCRAPE_EXAMPLES_HELP_MD;
+    let mut ids = IdMap::default();
+    format!(
+        "<div class=\"main-heading\">
+            <h1 class=\"fqn\">\
+                <span class=\"in-band\">About scraped examples</span>\
+            </h1>\
+        </div>\
+        <div>{}</div>",
+        Markdown {
+            content,
+            links: &[],
+            ids: &mut ids,
+            error_codes: shared.codes,
+            edition: shared.edition(),
+            playground: &shared.playground,
+            heading_offset: HeadingOffset::H1
+        }
+        .into_string()
+    )
+}
+
 fn document(
     w: &mut Buffer,
     cx: &Context<'_>,
@@ -2672,9 +2695,9 @@ fn render_call_locations(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item) {
           <span></span>\
           <h5 id=\"{id}\">\
              <a href=\"#{id}\">Examples found in repository</a>\
-             <a class=\"scrape-help\" href=\"{doc_prefix}/rustdoc/scraped-examples.html\" target=\"_blank\">?</a>\
+             <a class=\"scrape-help\" href=\"{root_path}scrape-examples-help.html\">?</a>\
           </h5>",
-        doc_prefix = DOC_RUST_LANG_ORG_CHANNEL,
+        root_path = cx.root_path(),
         id = id
     );
 

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;

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;
 }

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;
 }

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;
 }

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.

src/librustdoc/html/static_files.rs

@@ -39,6 +39,8 @@ crate static STORAGE_JS: &str = include_str!("static/js/storage.js");
 /// --scrape-examples flag that inserts automatically-found examples of usages of items.
 crate static SCRAPE_EXAMPLES_JS: &str = include_str!("static/js/scrape-examples.js");
 
+crate static SCRAPE_EXAMPLES_HELP_MD: &str = include_str!("static/scrape-examples-help.md");
+
 /// The file contents of `brush.svg`, the icon used for the theme-switch button.
 crate static BRUSH_SVG: &[u8] = include_bytes!("static/images/brush.svg");