diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs index 34784bbed0cf5..90123655758cc 100644 --- a/src/librustdoc/html/render/context.rs +++ b/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 = diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index c3e2eb81e45d2..80a18038272c7 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/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) -> Result) -> String { + let content = SCRAPE_EXAMPLES_HELP_MD; + let mut ids = IdMap::default(); + format!( + "
+

\ + About scraped examples\ +

\ +
\ +
{}
", + 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) { \
\ Examples found in repository\ - ?\ + ?\
", - doc_prefix = DOC_RUST_LANG_ORG_CHANNEL, + root_path = cx.root_path(), id = id ); diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index 55a11652c2353..e3c3d614f015c 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 e073057528c79..b1bf06c1865c7 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 a10029b637177..236304ccc9f1b 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 a30dcac66dbc5..c923902aba2d3 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 0000000000000..035b2e18b00eb --- /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. diff --git a/src/librustdoc/html/static_files.rs b/src/librustdoc/html/static_files.rs index cd369a93d8283..1837e4a3b650a 100644 --- a/src/librustdoc/html/static_files.rs +++ b/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");