1 # Command-line arguments
3 Here's the list of arguments you can pass to `rustdoc`:
7 Using this flag looks like this:
14 This will show `rustdoc`'s built-in help, which largely consists of
15 a list of possible command-line flags.
17 Some of `rustdoc`'s flags are unstable; this page only shows stable
18 options, `--help` will show them all.
20 ## `-V`/`--version`: version information
22 Using this flag looks like this:
29 This will show `rustdoc`'s version, which will look something
33 rustdoc 1.17.0 (56124baa9 2017-04-24)
36 ## `-v`/`--verbose`: more verbose output
38 Using this flag looks like this:
41 $ rustdoc -v src/lib.rs
42 $ rustdoc --verbose src/lib.rs
45 This enables "verbose mode", which means that more information will be written
46 to standard out. What is written depends on the other flags you've passed in.
47 For example, with `--version`:
50 $ rustdoc --verbose --version
51 rustdoc 1.17.0 (56124baa9 2017-04-24)
60 ## `-o`/`--out-dir`: output directory path
62 Using this flag looks like this:
65 $ rustdoc src/lib.rs -o target/doc
66 $ rustdoc src/lib.rs --out-dir target/doc
69 By default, `rustdoc`'s output appears in a directory named `doc` in
70 the current working directory. With this flag, it will place all output
71 into the directory you specify.
74 ## `--crate-name`: controlling the name of the crate
76 Using this flag looks like this:
79 $ rustdoc src/lib.rs --crate-name mycrate
82 By default, `rustdoc` assumes that the name of your crate is the same name
83 as the `.rs` file. `--crate-name` lets you override this assumption with
84 whatever name you choose.
86 ## `--document-private-items`: Show items that are not public
88 Using this flag looks like this:
91 $ rustdoc src/lib.rs --document-private-items
94 By default, `rustdoc` only documents items that are publicly reachable.
97 pub fn public() {} // this item is public and will be documented
98 mod private { // this item is private and will not be documented
99 pub fn unreachable() {} // this item is public, but unreachable, so it will not be documented
103 `--document-private-items` documents all items, even if they're not public.
105 ## `-L`/`--library-path`: where to look for dependencies
107 Using this flag looks like this:
110 $ rustdoc src/lib.rs -L target/debug/deps
111 $ rustdoc src/lib.rs --library-path target/debug/deps
114 If your crate has dependencies, `rustdoc` needs to know where to find them.
115 Passing `--library-path` gives `rustdoc` a list of places to look for these
118 This flag takes any number of directories as its argument, and will use all of
122 ## `--cfg`: passing configuration flags
124 Using this flag looks like this:
127 $ rustdoc src/lib.rs --cfg feature="foo"
130 This flag accepts the same values as `rustc --cfg`, and uses it to configure
131 compilation. The example above uses `feature`, but any of the `cfg` values
134 ## `--extern`: specify a dependency's location
136 Using this flag looks like this:
139 $ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static
142 Similar to `--library-path`, `--extern` is about specifying the location
143 of a dependency. `--library-path` provides directories to search in, `--extern`
144 instead lets you specify exactly which dependency is located where.
146 ## `-C`/`--codegen`: pass codegen options to rustc
148 Using this flag looks like this:
151 $ rustdoc src/lib.rs -C target_feature=+avx
152 $ rustdoc src/lib.rs --codegen target_feature=+avx
154 $ rustdoc --test src/lib.rs -C target_feature=+avx
155 $ rustdoc --test src/lib.rs --codegen target_feature=+avx
157 $ rustdoc --test README.md -C target_feature=+avx
158 $ rustdoc --test README.md --codegen target_feature=+avx
161 When rustdoc generates documentation, looks for documentation tests, or executes documentation
162 tests, it needs to compile some rust code, at least part-way. This flag allows you to tell rustdoc
163 to provide some extra codegen options to rustc when it runs these compilations. Most of the time,
164 these options won't affect a regular documentation run, but if something depends on target features
165 to be enabled, or documentation tests need to use some additional options, this flag allows you to
168 The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
171 ## `--test`: run code examples as tests
173 Using this flag looks like this:
176 $ rustdoc src/lib.rs --test
179 This flag will run your code examples as tests. For more, see [the chapter
180 on documentation tests](write-documentation/documentation-tests.md).
182 See also `--test-args`.
184 ## `--test-args`: pass options to test runner
186 Using this flag looks like this:
189 $ rustdoc src/lib.rs --test --test-args ignored
192 This flag will pass options to the test runner when running documentation tests.
193 For more, see [the chapter on documentation tests](write-documentation/documentation-tests.md).
197 ## `--target`: generate documentation for the specified target triple
199 Using this flag looks like this:
202 $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
205 Similar to the `--target` flag for `rustc`, this generates documentation
206 for a target triple that's different than your host triple.
208 All of the usual caveats of cross-compiling code apply.
210 ## `--default-theme`: set the default theme
212 Using this flag looks like this:
215 $ rustdoc src/lib.rs --default-theme=ayu
218 Sets the default theme (for users whose browser has not remembered a
219 previous theme selection from the on-page theme picker).
221 The supplied value should be the lowercase version of the theme name.
222 The set of available themes can be seen in the theme picker in the
225 Note that the set of available themes - and their appearance - is not
226 necessarily stable from one rustdoc version to the next. If the
227 requested theme does not exist, the builtin default (currently
228 `light`) is used instead.
230 ## `--markdown-css`: include more CSS files when rendering markdown
232 Using this flag looks like this:
235 $ rustdoc README.md --markdown-css foo.css
238 When rendering Markdown files, this will create a `<link>` element in the
239 `<head>` section of the generated HTML. For example, with the invocation above,
242 <link rel="stylesheet" type="text/css" href="foo.css">
247 When rendering Rust files, this flag is ignored.
249 ## `--html-in-header`: include more HTML in <head>
251 Using this flag looks like this:
254 $ rustdoc src/lib.rs --html-in-header header.html
255 $ rustdoc README.md --html-in-header header.html
258 This flag takes a list of files, and inserts them into the `<head>` section of
259 the rendered documentation.
261 ## `--html-before-content`: include more HTML before the content
263 Using this flag looks like this:
266 $ rustdoc src/lib.rs --html-before-content extra.html
267 $ rustdoc README.md --html-before-content extra.html
270 This flag takes a list of files, and inserts them inside the `<body>` tag but
271 before the other content `rustdoc` would normally produce in the rendered
274 ## `--html-after-content`: include more HTML after the content
276 Using this flag looks like this:
279 $ rustdoc src/lib.rs --html-after-content extra.html
280 $ rustdoc README.md --html-after-content extra.html
283 This flag takes a list of files, and inserts them before the `</body>` tag but
284 after the other content `rustdoc` would normally produce in the rendered
288 ## `--markdown-playground-url`: control the location of the playground
290 Using this flag looks like this:
293 $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
296 When rendering a Markdown file, this flag gives the base URL of the Rust
297 Playground, to use for generating `Run` buttons.
300 ## `--markdown-no-toc`: don't generate a table of contents
302 Using this flag looks like this:
305 $ rustdoc README.md --markdown-no-toc
308 When generating documentation from a Markdown file, by default, `rustdoc` will
309 generate a table of contents. This flag suppresses that, and no TOC will be
313 ## `-e`/`--extend-css`: extend rustdoc's CSS
315 Using this flag looks like this:
318 $ rustdoc src/lib.rs -e extra.css
319 $ rustdoc src/lib.rs --extend-css extra.css
322 With this flag, the contents of the files you pass are included at the bottom
323 of Rustdoc's `theme.css` file.
325 While this flag is stable, the contents of `theme.css` are not, so be careful!
326 Updates may break your theme extensions.
328 ## `--sysroot`: override the system root
330 Using this flag looks like this:
333 $ rustdoc src/lib.rs --sysroot /path/to/sysroot
336 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
337 when compiling your code.
339 ## `--edition`: control the edition of docs and doctests
341 Using this flag looks like this:
344 $ rustdoc src/lib.rs --edition 2018
345 $ rustdoc --test src/lib.rs --edition 2018
348 This flag allows `rustdoc` to treat your rust code as the given edition. It will compile doctests with
349 the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
352 ## `--theme`: add a theme to the documentation output
354 Using this flag looks like this:
357 $ rustdoc src/lib.rs --theme /path/to/your/custom-theme.css
360 `rustdoc`'s default output includes two themes: `light` (the default) and
361 `dark`. This flag allows you to add custom themes to the output. Giving a CSS
362 file to this flag adds it to your documentation as an additional theme choice.
363 The theme's name is determined by its filename; a theme file named
364 `custom-theme.css` will add a theme named `custom-theme` to the documentation.
366 ## `--check-theme`: verify custom themes against the default theme
368 Using this flag looks like this:
371 $ rustdoc --check-theme /path/to/your/custom-theme.css
374 While `rustdoc`'s HTML output is more-or-less consistent between versions, there
375 is no guarantee that a theme file will have the same effect. The `--theme` flag
376 will still allow you to add the theme to your documentation, but to ensure that
377 your theme works as expected, you can use this flag to verify that it implements
378 the same CSS rules as the official `light` theme.
380 `--check-theme` is a separate mode in `rustdoc`. When `rustdoc` sees the
381 `--check-theme` flag, it discards all other flags and only performs the CSS rule
382 comparison operation.
384 ## `--crate-version`: control the crate version
386 Using this flag looks like this:
389 $ rustdoc src/lib.rs --crate-version 1.3.37
392 When `rustdoc` receives this flag, it will print an extra "Version (version)" into the sidebar of
393 the crate root's docs. You can use this flag to differentiate between different versions of your
394 library's documentation.
396 ## `@path`: load command-line flags from a path
398 If you specify `@path` on the command-line, then it will open `path` and read
399 command line options from it. These options are one per line; a blank line indicates
400 an empty option. The file can use Unix or Windows style line endings, and must be
403 ## `--passes`: add more rustdoc passes
405 This flag is **deprecated**.
406 For more details on passes, see [the chapter on them](deprecated-features.md#passes).
408 ## `--no-defaults`: don't run default passes
410 This flag is **deprecated**.
411 For more details on passes, see [the chapter on them](deprecated-features.md#passes).
413 ## `-r`/`--input-format`: input format
415 This flag is **deprecated** and **has no effect**.
417 Rustdoc only supports Rust source code and Markdown input formats. If the
418 file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
419 Otherwise, it assumes that the input file is Rust.