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 ## `-r`/`--input-format`: input format
62 This flag is currently ignored; the idea is that `rustdoc` would support various
63 input formats, and you could specify them via this flag.
65 Rustdoc only supports Rust source code and Markdown input formats. If the
66 file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
67 Otherwise, it assumes that the input file is Rust.
70 ## `-w`/`--output-format`: output format
72 This flag is currently ignored; the idea is that `rustdoc` would support
73 various output formats, and you could specify them via this flag.
75 Rustdoc only supports HTML output, and so this flag is redundant today.
77 ## `-o`/`--output`: output path
79 Using this flag looks like this:
82 $ rustdoc src/lib.rs -o target/doc
83 $ rustdoc src/lib.rs --output target/doc
86 By default, `rustdoc`'s output appears in a directory named `doc` in
87 the current working directory. With this flag, it will place all output
88 into the directory you specify.
91 ## `--crate-name`: controlling the name of the crate
93 Using this flag looks like this:
96 $ rustdoc src/lib.rs --crate-name mycrate
99 By default, `rustdoc` assumes that the name of your crate is the same name
100 as the `.rs` file. `--crate-name` lets you override this assumption with
101 whatever name you choose.
103 ## `-L`/`--library-path`: where to look for dependencies
105 Using this flag looks like this:
108 $ rustdoc src/lib.rs -L target/debug/deps
109 $ rustdoc src/lib.rs --library-path target/debug/deps
112 If your crate has dependencies, `rustdoc` needs to know where to find them.
113 Passing `--library-path` gives `rustdoc` a list of places to look for these
116 This flag takes any number of directories as its argument, and will use all of
120 ## `--cfg`: passing configuration flags
122 Using this flag looks like this:
125 $ rustdoc src/lib.rs --cfg feature="foo"
128 This flag accepts the same values as `rustc --cfg`, and uses it to configure
129 compilation. The example above uses `feature`, but any of the `cfg` values
132 ## `--extern`: specify a dependency's location
134 Using this flag looks like this:
137 $ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static
140 Similar to `--library-path`, `--extern` is about specifying the location
141 of a dependency. `--library-path` provides directories to search in, `--extern`
142 instead lets you specify exactly which dependency is located where.
144 ## `-C`/`--codegen`: pass codegen options to rustc
146 Using this flag looks like this:
149 $ rustdoc src/lib.rs -C target_feature=+avx
150 $ rustdoc src/lib.rs --codegen target_feature=+avx
152 $ rustdoc --test src/lib.rs -C target_feature=+avx
153 $ rustdoc --test src/lib.rs --codegen target_feature=+avx
155 $ rustdoc --test README.md -C target_feature=+avx
156 $ rustdoc --test README.md --codegen target_feature=+avx
159 When rustdoc generates documentation, looks for documentation tests, or executes documentation
160 tests, it needs to compile some rust code, at least part-way. This flag allows you to tell rustdoc
161 to provide some extra codegen options to rustc when it runs these compilations. Most of the time,
162 these options won't affect a regular documentation run, but if something depends on target features
163 to be enabled, or documentation tests need to use some additional options, this flag allows you to
166 The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
169 ## `--passes`: add more rustdoc passes
171 Using this flag looks like this:
174 $ rustdoc --passes list
175 $ rustdoc src/lib.rs --passes strip-priv-imports
178 An argument of "list" will print a list of possible "rustdoc passes", and other
179 arguments will be the name of which passes to run in addition to the defaults.
181 For more details on passes, see [the chapter on them](passes.md).
183 See also `--no-defaults`.
185 ## `--no-defaults`: don't run default passes
187 Using this flag looks like this:
190 $ rustdoc src/lib.rs --no-defaults
193 By default, `rustdoc` will run several passes over your code. This
194 removes those defaults, allowing you to use `--passes` to specify
195 exactly which passes you want.
197 For more details on passes, see [the chapter on them](passes.md).
201 ## `--test`: run code examples as tests
203 Using this flag looks like this:
206 $ rustdoc src/lib.rs --test
209 This flag will run your code examples as tests. For more, see [the chapter
210 on documentation tests](documentation-tests.md).
212 See also `--test-args`.
214 ## `--test-args`: pass options to test runner
216 Using this flag looks like this:
219 $ rustdoc src/lib.rs --test --test-args ignored
222 This flag will pass options to the test runner when running documentation tests.
223 For more, see [the chapter on documentation tests](documentation-tests.md).
227 ## `--target`: generate documentation for the specified target triple
229 Using this flag looks like this:
232 $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
235 Similar to the `--target` flag for `rustc`, this generates documentation
236 for a target triple that's different than your host triple.
238 All of the usual caveats of cross-compiling code apply.
240 ## `--default-theme`: set the default theme
242 Using this flag looks like this:
245 $ rustdoc src/lib.rs --default-theme=ayu
248 Sets the default theme (for users whose browser has not remembered a
249 previous theme selection from the on-page theme picker).
251 The supplied value should be the lowercase version of the theme name.
252 The set of available themes can be seen in the theme picker in the
255 Note that the set of available themes - and their appearance - is not
256 necessarily stable from one rustdoc version to the next. If the
257 requested theme does not exist, the builtin default (currently
258 `light`) is used instead.
260 ## `--markdown-css`: include more CSS files when rendering markdown
262 Using this flag looks like this:
265 $ rustdoc README.md --markdown-css foo.css
268 When rendering Markdown files, this will create a `<link>` element in the
269 `<head>` section of the generated HTML. For example, with the invocation above,
272 <link rel="stylesheet" type="text/css" href="foo.css">
277 When rendering Rust files, this flag is ignored.
279 ## `--html-in-header`: include more HTML in <head>
281 Using this flag looks like this:
284 $ rustdoc src/lib.rs --html-in-header header.html
285 $ rustdoc README.md --html-in-header header.html
288 This flag takes a list of files, and inserts them into the `<head>` section of
289 the rendered documentation.
291 ## `--html-before-content`: include more HTML before the content
293 Using this flag looks like this:
296 $ rustdoc src/lib.rs --html-before-content extra.html
297 $ rustdoc README.md --html-before-content extra.html
300 This flag takes a list of files, and inserts them inside the `<body>` tag but
301 before the other content `rustdoc` would normally produce in the rendered
304 ## `--html-after-content`: include more HTML after the content
306 Using this flag looks like this:
309 $ rustdoc src/lib.rs --html-after-content extra.html
310 $ rustdoc README.md --html-after-content extra.html
313 This flag takes a list of files, and inserts them before the `</body>` tag but
314 after the other content `rustdoc` would normally produce in the rendered
318 ## `--markdown-playground-url`: control the location of the playground
320 Using this flag looks like this:
323 $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
326 When rendering a Markdown file, this flag gives the base URL of the Rust
327 Playground, to use for generating `Run` buttons.
330 ## `--markdown-no-toc`: don't generate a table of contents
332 Using this flag looks like this:
335 $ rustdoc README.md --markdown-no-toc
338 When generating documentation from a Markdown file, by default, `rustdoc` will
339 generate a table of contents. This flag suppresses that, and no TOC will be
343 ## `-e`/`--extend-css`: extend rustdoc's CSS
345 Using this flag looks like this:
348 $ rustdoc src/lib.rs -e extra.css
349 $ rustdoc src/lib.rs --extend-css extra.css
352 With this flag, the contents of the files you pass are included at the bottom
353 of Rustdoc's `theme.css` file.
355 While this flag is stable, the contents of `theme.css` are not, so be careful!
356 Updates may break your theme extensions.
358 ## `--sysroot`: override the system root
360 Using this flag looks like this:
363 $ rustdoc src/lib.rs --sysroot /path/to/sysroot
366 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
367 when compiling your code.
369 ### `--edition`: control the edition of docs and doctests
371 Using this flag looks like this:
374 $ rustdoc src/lib.rs --edition 2018
375 $ rustdoc --test src/lib.rs --edition 2018
378 This flag allows `rustdoc` to treat your rust code as the given edition. It will compile doctests with
379 the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
382 ## `--theme`: add a theme to the documentation output
384 Using this flag looks like this:
387 $ rustdoc src/lib.rs --theme /path/to/your/custom-theme.css
390 `rustdoc`'s default output includes two themes: `light` (the default) and
391 `dark`. This flag allows you to add custom themes to the output. Giving a CSS
392 file to this flag adds it to your documentation as an additional theme choice.
393 The theme's name is determined by its filename; a theme file named
394 `custom-theme.css` will add a theme named `custom-theme` to the documentation.
396 ## `--check-theme`: verify custom themes against the default theme
398 Using this flag looks like this:
401 $ rustdoc --check-theme /path/to/your/custom-theme.css
404 While `rustdoc`'s HTML output is more-or-less consistent between versions, there
405 is no guarantee that a theme file will have the same effect. The `--theme` flag
406 will still allow you to add the theme to your documentation, but to ensure that
407 your theme works as expected, you can use this flag to verify that it implements
408 the same CSS rules as the official `light` theme.
410 `--check-theme` is a separate mode in `rustdoc`. When `rustdoc` sees the
411 `--check-theme` flag, it discards all other flags and only performs the CSS rule
412 comparison operation.
414 ### `--crate-version`: control the crate version
416 Using this flag looks like this:
419 $ rustdoc src/lib.rs --crate-version 1.3.37
422 When `rustdoc` receives this flag, it will print an extra "Version (version)" into the sidebar of
423 the crate root's docs. You can use this flag to differentiate between different versions of your
424 library's documentation.