RUSTDOC(1)

📦 version 1.96.1, in ubuntu stonking

✨ RUSTDOC(1) ✨

okay bestie, welcome to rustdoc — it's a User Command, it lives in section 1 of the manual, and it is genuinely one of the most useful little gremlins in the whole Rust toolbox. let's get into it 💖

🌸 NAME 🌸

rustdoc — generate documentation from Rust source code. that's it. that's the girl. she reads your comments and turns them into a whole website. iconic behavior honestly 💅

🎀 SYNOPSIS 🎀

rustdoc [OPTIONS] INPUT

so like. options first, then the input. in that order. don't fight it.

🦋 DESCRIPTION 🦋

This tool generates API reference documentation by extracting comments from source code written in the Rust language, available at <https://www.rust-lang.org>. It accepts several input formats and provides several output formats for the generated documentation.

fr fr, it just goes through your Rust code, scoops out the doc comments you wrote, and serves them up as pretty documentation. she's flexible too — multiple input formats go in, multiple output formats come out. main character energy 🫶

✨ OPTIONS ✨

one bullet per flag, no skipping, we're doing all of them:

  • -r, --input-format FORMAT — rust
  • -w, --output-format FORMAT — html
  • -o, --output OUTPUT, — where to place the output (default: doc/ for html)
  • --passes LIST — space-separated list of passes to run (default: '')
  • --no-defaults — don't run the default passes. like, skip the usual routine entirely 🙈
  • --plugins LIST — space-separated list of plugins to run (default: '')
  • --plugin-path DIR — directory to load plugins from (default: /tmp/rustdoc_ng/plugins)
  • --target TRIPLE — target triple to document
  • --crate-name NAME — specify the name of this crate
  • -L, --library-path DIR — directory to add to crate search path
  • --cfg SPEC — pass a --cfg to rustc
  • --extern VAL — pass an --extern to rustc
  • --test — run code examples as tests
  • --test-args ARGS — pass arguments to the test runner
  • --html-in-header FILE — file to add to <head>
  • --html-before-content FILES — files to include inline between <body> and the content of a rendered Markdown file or generated documentation
  • --markdown-before-content FILES — files to include inline between <body> and the content of a rendered Markdown file or generated documentation
  • --html-after-content FILES — files to include inline between the content and </body> of a rendered Markdown file or generated documentation
  • --markdown-after-content FILES — files to include inline between the content and </body> of a rendered Markdown file or generated documentation
  • --markdown-css FILES — CSS files to include via <link> in a rendered Markdown file Markdown file or generated documentation
  • --markdown-playground-url URL — URL to send code snippets to
  • --markdown-no-toc — don't include table of contents
  • -h, --extend-css — to redefine some css rules with a given file to generate doc with your own theme
  • -V, --version — Print rustdoc's version
ngl, yes, that -h really is --extend-css in this manpage. we don't make the rules, we just document them exactly as they are. no cap 💀

🌈 OUTPUT FORMATS 🌈

The rustdoc tool can generate output in an HTML format.

If using an HTML format, then the specified output destination will be the root directory of an HTML structure for all the documentation. Pages will be placed into this directory, and source files will also possibly be rendered into it as well.

so basically: you point her at a folder, she makes that folder the root of the whole HTML situation. pages go in there, source files might get rendered in there too. it's giving little documentation ecosystem 🧚

💜 EXAMPLES 💜

To generate documentation for the source in the current directory:

$ rustdoc hello.rs

List all available passes that rustdoc has, along with default passes:

$ rustdoc --passes list

The generated HTML can be viewed with any standard web browser.

look at that. two commands. so easy. go open it in a browser and feel like a genius 👑

⭐ SEE ALSO ⭐

💀 BUGS 💀

See <https://github.com/rust-lang/rust/issues> for issues.

(yes bestie, bugs happen, that's literally where you report them 🍓)

🌸 AUTHOR 🌸

See the version control history or <https://thanks.rust-lang.org>

This work is dual-licensed under Apache 2.0 and MIT terms. See COPYRIGHT file in the rust source distribution.

and that's the whole page, bestie 💖 this one's from the rustdoc manual, version <INSERT VERSION HERE>, dated July 2018. slay, go document something 🦋✨

📦 where this page comes from