diff options
| -rw-r--r-- | src/doc/rustdoc/src/unstable-features.md | 14 | ||||
| -rw-r--r-- | src/librustdoc/html/render/mod.rs | 7 | ||||
| -rw-r--r-- | src/librustdoc/html/static/css/rustdoc.css | 8 | ||||
| -rw-r--r-- | src/librustdoc/scrape_examples.rs | 2 |
4 files changed, 23 insertions, 8 deletions
diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index 91795997641..ea8589116b9 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -455,3 +455,17 @@ Calculating code examples follows these rules: * static * typedef 2. If one of the previously listed items has a code example, then it'll be counted. + +### `--with-examples`: include examples of uses of items as documentation + +This option, combined with `--scrape-examples-target-crate` and `--scrape-examples-output-path`, is used to implement the functionality in [RFC #3123](https://github.com/rust-lang/rfcs/pull/3123). Uses of an item (currently functions / call-sites) are found in a crate and its reverse-dependencies, and then the uses are included as documentation for that item. This feature is intended to be used via `cargo doc --scrape-examples`, but the rustdoc-only workflow looks like: + +```bash +$ rustdoc examples/ex.rs -Z unstable-options \ + --extern foobar=target/deps/libfoobar.rmeta + --scrape-examples-target-crate foobar \ + --scrape-examples-output-path output.calls +$ rustdoc src/lib.rs -Z unstable-options --with-examples output.calls +``` + +First, the library must be checked to generate an `rmeta`. Then a reverse-dependency like `examples/ex.rs` is given to rustdoc with the target crate being documented (`foobar`) and a path to output the calls (`output.calls`). Then, the generated calls file can be passed via `--with-examples` to the subsequent documentation of `foobar`. diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 2454ae492b2..d5e8d8b4906 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -72,8 +72,8 @@ use crate::html::format::{ href, print_abi_with_space, print_constness_with_space, print_default_space, print_generic_bounds, print_where_clause, Buffer, HrefError, PrintWithSpace, }; -use crate::html::markdown::{HeadingOffset, Markdown, MarkdownHtml, MarkdownSummaryLine}; use crate::html::highlight; +use crate::html::markdown::{HeadingOffset, Markdown, MarkdownHtml, MarkdownSummaryLine}; use crate::html::sources; use crate::scrape_examples::CallData; @@ -2479,9 +2479,10 @@ fn render_call_locations(w: &mut Buffer, cx: &Context<'_>, def_id: DefId, item: write!( w, "<div class=\"docblock scraped-example-list\">\ - <h1 id=\"scraped-examples\" class=\"small-section-header\">\ + <span></span> + <h5 id=\"scraped-examples\" class=\"section-header\">\ <a href=\"#{}\">Examples found in repository</a>\ - </h1>", + </h5>", id ); diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index b7d9a30beb1..7ebeffe85dd 100644 --- a/src/librustdoc/html/static/css/rustdoc.css +++ b/src/librustdoc/html/static/css/rustdoc.css @@ -2071,6 +2071,10 @@ details.undocumented[open] > summary::before { background: #f6fdb0; } +.more-examples-toggle { + margin-top: 10px; +} + .more-examples-toggle summary { color: #999; font-family: 'Fira Sans'; @@ -2106,10 +2110,6 @@ details.undocumented[open] > summary::before { height: 100%; } -h1 + .scraped-example { - margin-bottom: 10px; -} - .more-scraped-examples .scraped-example { margin-bottom: 20px; } diff --git a/src/librustdoc/scrape_examples.rs b/src/librustdoc/scrape_examples.rs index bb3cb016e2e..3a8e5337f5b 100644 --- a/src/librustdoc/scrape_examples.rs +++ b/src/librustdoc/scrape_examples.rs @@ -216,7 +216,7 @@ crate fn run( // Run call-finder on all items let mut calls = FxHashMap::default(); let mut finder = FindCalls { calls: &mut calls, tcx, map: tcx.hir(), cx, target_crates }; - tcx.hir().krate().visit_all_item_likes(&mut finder.as_deep_visitor()); + tcx.hir().visit_all_item_likes(&mut finder.as_deep_visitor()); // Save output to provided path let mut encoder = FileEncoder::new(options.output_path).map_err(|e| e.to_string())?; |