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 ## `--passes`: add more rustdoc passes
146 Using this flag looks like this:
149 $ rustdoc --passes list
150 $ rustdoc src/lib.rs --passes strip-priv-imports
153 An argument of "list" will print a list of possible "rustdoc passes", and other
154 arguments will be the name of which passes to run in addition to the defaults.
156 For more details on passes, see [the chapter on them](passes.html).
158 See also `--no-defaults`.
160 ## `--no-defaults`: don't run default passes
162 Using this flag looks like this:
165 $ rustdoc src/lib.rs --no-defaults
168 By default, `rustdoc` will run several passes over your code. This
169 removes those defaults, allowing you to use `--passes` to specify
170 exactly which passes you want.
172 For more details on passes, see [the chapter on them](passes.html).
176 ## `--test`: run code examples as tests
178 Using this flag looks like this:
181 $ rustdoc src/lib.rs --test
184 This flag will run your code examples as tests. For more, see [the chapter
185 on documentation tests](documentation-tests.html).
187 See also `--test-args`.
189 ## `--test-args`: pass options to test runner
191 Using this flag looks like this:
194 $ rustdoc src/lib.rs --test --test-args ignored
197 This flag will pass options to the test runner when running documentation tests.
198 For more, see [the chapter on documentation tests](documentation-tests.html).
202 ## `--target`: generate documentation for the specified target triple
204 Using this flag looks like this:
207 $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
210 Similar to the `--target` flag for `rustc`, this generates documentation
211 for a target triple that's different than your host triple.
213 All of the usual caveats of cross-compiling code apply.
215 ## `--markdown-css`: include more CSS files when rendering markdown
217 Using this flag looks like this:
220 $ rustdoc README.md --markdown-css foo.css
223 When rendering Markdown files, this will create a `<link>` element in the
224 `<head>` section of the generated HTML. For example, with the invocation above,
227 <link rel="stylesheet" type="text/css" href="foo.css">
232 When rendering Rust files, this flag is ignored.
234 ## `--html-in-header`: include more HTML in <head>
236 Using this flag looks like this:
239 $ rustdoc src/lib.rs --html-in-header header.html
240 $ rustdoc README.md --html-in-header header.html
243 This flag takes a list of files, and inserts them into the `<head>` section of
244 the rendered documentation.
246 ## `--html-before-content`: include more HTML before the content
248 Using this flag looks like this:
251 $ rustdoc src/lib.rs --html-before-content extra.html
252 $ rustdoc README.md --html-before-content extra.html
255 This flag takes a list of files, and inserts them inside the `<body>` tag but
256 before the other content `rustdoc` would normally produce in the rendered
259 ## `--html-after-content`: include more HTML after the content
261 Using this flag looks like this:
264 $ rustdoc src/lib.rs --html-after-content extra.html
265 $ rustdoc README.md --html-after-content extra.html
268 This flag takes a list of files, and inserts them before the `</body>` tag but
269 after the other content `rustdoc` would normally produce in the rendered
273 ## `--markdown-playground-url`: control the location of the playground
275 Using this flag looks like this:
278 $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
281 When rendering a Markdown file, this flag gives the base URL of the Rust
282 Playround, to use for generating `Run` buttons.
285 ## `--markdown-no-toc`: don't generate a table of contents
287 Using this flag looks like this:
290 $ rustdoc README.md --markdown-no-toc
293 When generating documentation from a Markdown file, by default, `rustdoc` will
294 generate a table of contents. This flag supresses that, and no TOC will be
298 ## `-e`/`--extend-css`: extend rustdoc's CSS
300 Using this flag looks like this:
303 $ rustdoc src/lib.rs -e extra.css
304 $ rustdoc src/lib.rs --extend-css extra.css
307 With this flag, the contents of the files you pass are included at the bottom
308 of Rustdoc's `theme.css` file.
310 While this flag is stable, the contents of `theme.css` are not, so be careful!
311 Updates may break your theme extensions.
313 ## `--sysroot`: override the system root
315 Using this flag looks like this:
318 $ rustdoc src/lib.rs --sysroot /path/to/sysroot
321 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
322 when compiling your code.