]>
Commit | Line | Data |
---|---|---|
041b39d2 XL |
1 | # Command-line arguments |
2 | ||
3 | Here's the list of arguments you can pass to `rustdoc`: | |
4 | ||
5 | ## `-h`/`--help`: help | |
6 | ||
7 | Using this flag looks like this: | |
8 | ||
9 | ```bash | |
10 | $ rustdoc -h | |
11 | $ rustdoc --help | |
12 | ``` | |
13 | ||
14 | This will show `rustdoc`'s built-in help, which largely consists of | |
15 | a list of possible command-line flags. | |
16 | ||
17 | Some of `rustdoc`'s flags are unstable; this page only shows stable | |
18 | options, `--help` will show them all. | |
19 | ||
20 | ## `-V`/`--version`: version information | |
21 | ||
22 | Using this flag looks like this: | |
23 | ||
24 | ```bash | |
25 | $ rustdoc -V | |
26 | $ rustdoc --version | |
27 | ``` | |
28 | ||
29 | This will show `rustdoc`'s version, which will look something | |
30 | like this: | |
31 | ||
32 | ```text | |
33 | rustdoc 1.17.0 (56124baa9 2017-04-24) | |
34 | ``` | |
35 | ||
36 | ## `-v`/`--verbose`: more verbose output | |
37 | ||
38 | Using this flag looks like this: | |
39 | ||
40 | ```bash | |
41 | $ rustdoc -v src/lib.rs | |
42 | $ rustdoc --verbose src/lib.rs | |
43 | ``` | |
44 | ||
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`: | |
48 | ||
49 | ```text | |
50 | $ rustdoc --verbose --version | |
51 | rustdoc 1.17.0 (56124baa9 2017-04-24) | |
52 | binary: rustdoc | |
53 | commit-hash: hash | |
54 | commit-date: date | |
55 | host: host-triple | |
56 | release: 1.17.0 | |
57 | LLVM version: 3.9 | |
58 | ``` | |
59 | ||
041b39d2 XL |
60 | ## `-o`/`--output`: output path |
61 | ||
62 | Using this flag looks like this: | |
63 | ||
64 | ```bash | |
ba9703b0 XL |
65 | $ rustdoc src/lib.rs -o target/doc |
66 | $ rustdoc src/lib.rs --output target/doc | |
041b39d2 XL |
67 | ``` |
68 | ||
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. | |
72 | ||
73 | ||
74 | ## `--crate-name`: controlling the name of the crate | |
75 | ||
76 | Using this flag looks like this: | |
77 | ||
78 | ```bash | |
79 | $ rustdoc src/lib.rs --crate-name mycrate | |
80 | ``` | |
81 | ||
abe05a73 | 82 | By default, `rustdoc` assumes that the name of your crate is the same name |
041b39d2 XL |
83 | as the `.rs` file. `--crate-name` lets you override this assumption with |
84 | whatever name you choose. | |
85 | ||
6a06907d XL |
86 | ## `--document-private-items`: Show items that are not public |
87 | ||
88 | Using this flag looks like this: | |
89 | ||
90 | ```bash | |
91 | $ rustdoc src/lib.rs --document-private-items | |
92 | ``` | |
93 | ||
94 | By default, `rustdoc` only documents items that are publicly reachable. | |
95 | ||
96 | ```rust | |
97 | pub fn public() {} // this item is public and will 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 | |
100 | } | |
101 | ``` | |
102 | ||
103 | `--document-private-items` documents all items, even if they're not public. | |
104 | ||
abe05a73 | 105 | ## `-L`/`--library-path`: where to look for dependencies |
041b39d2 XL |
106 | |
107 | Using this flag looks like this: | |
108 | ||
109 | ```bash | |
110 | $ rustdoc src/lib.rs -L target/debug/deps | |
111 | $ rustdoc src/lib.rs --library-path target/debug/deps | |
112 | ``` | |
113 | ||
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 | |
116 | dependencies. | |
117 | ||
118 | This flag takes any number of directories as its argument, and will use all of | |
119 | them when searching. | |
120 | ||
121 | ||
122 | ## `--cfg`: passing configuration flags | |
123 | ||
124 | Using this flag looks like this: | |
125 | ||
126 | ```bash | |
127 | $ rustdoc src/lib.rs --cfg feature="foo" | |
128 | ``` | |
129 | ||
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 | |
132 | are acceptable. | |
133 | ||
134 | ## `--extern`: specify a dependency's location | |
135 | ||
136 | Using this flag looks like this: | |
137 | ||
138 | ```bash | |
139 | $ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static | |
140 | ``` | |
141 | ||
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. | |
145 | ||
83c7162d XL |
146 | ## `-C`/`--codegen`: pass codegen options to rustc |
147 | ||
148 | Using this flag looks like this: | |
149 | ||
150 | ```bash | |
151 | $ rustdoc src/lib.rs -C target_feature=+avx | |
152 | $ rustdoc src/lib.rs --codegen target_feature=+avx | |
153 | ||
154 | $ rustdoc --test src/lib.rs -C target_feature=+avx | |
155 | $ rustdoc --test src/lib.rs --codegen target_feature=+avx | |
156 | ||
157 | $ rustdoc --test README.md -C target_feature=+avx | |
158 | $ rustdoc --test README.md --codegen target_feature=+avx | |
159 | ``` | |
160 | ||
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 | |
166 | affect that. | |
167 | ||
168 | The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to | |
169 | get the full list. | |
170 | ||
041b39d2 XL |
171 | ## `--test`: run code examples as tests |
172 | ||
173 | Using this flag looks like this: | |
174 | ||
175 | ```bash | |
176 | $ rustdoc src/lib.rs --test | |
177 | ``` | |
178 | ||
179 | This flag will run your code examples as tests. For more, see [the chapter | |
dc9dc135 | 180 | on documentation tests](documentation-tests.md). |
041b39d2 XL |
181 | |
182 | See also `--test-args`. | |
183 | ||
abe05a73 | 184 | ## `--test-args`: pass options to test runner |
041b39d2 XL |
185 | |
186 | Using this flag looks like this: | |
187 | ||
188 | ```bash | |
189 | $ rustdoc src/lib.rs --test --test-args ignored | |
190 | ``` | |
191 | ||
192 | This flag will pass options to the test runner when running documentation tests. | |
dc9dc135 | 193 | For more, see [the chapter on documentation tests](documentation-tests.md). |
041b39d2 XL |
194 | |
195 | See also `--test`. | |
196 | ||
abe05a73 | 197 | ## `--target`: generate documentation for the specified target triple |
041b39d2 XL |
198 | |
199 | Using this flag looks like this: | |
200 | ||
201 | ```bash | |
202 | $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu | |
203 | ``` | |
204 | ||
205 | Similar to the `--target` flag for `rustc`, this generates documentation | |
206 | for a target triple that's different than your host triple. | |
207 | ||
208 | All of the usual caveats of cross-compiling code apply. | |
209 | ||
5869c6ff XL |
210 | ## `--default-theme`: set the default theme |
211 | ||
212 | Using this flag looks like this: | |
213 | ||
214 | ```bash | |
215 | $ rustdoc src/lib.rs --default-theme=ayu | |
216 | ``` | |
217 | ||
218 | Sets the default theme (for users whose browser has not remembered a | |
219 | previous theme selection from the on-page theme picker). | |
220 | ||
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 | |
223 | generated output. | |
224 | ||
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. | |
229 | ||
041b39d2 XL |
230 | ## `--markdown-css`: include more CSS files when rendering markdown |
231 | ||
232 | Using this flag looks like this: | |
233 | ||
234 | ```bash | |
235 | $ rustdoc README.md --markdown-css foo.css | |
236 | ``` | |
237 | ||
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, | |
240 | ||
241 | ```html | |
242 | <link rel="stylesheet" type="text/css" href="foo.css"> | |
243 | ``` | |
244 | ||
245 | will be added. | |
246 | ||
247 | When rendering Rust files, this flag is ignored. | |
248 | ||
249 | ## `--html-in-header`: include more HTML in <head> | |
250 | ||
251 | Using this flag looks like this: | |
252 | ||
253 | ```bash | |
254 | $ rustdoc src/lib.rs --html-in-header header.html | |
255 | $ rustdoc README.md --html-in-header header.html | |
256 | ``` | |
257 | ||
258 | This flag takes a list of files, and inserts them into the `<head>` section of | |
259 | the rendered documentation. | |
260 | ||
261 | ## `--html-before-content`: include more HTML before the content | |
262 | ||
263 | Using this flag looks like this: | |
264 | ||
265 | ```bash | |
266 | $ rustdoc src/lib.rs --html-before-content extra.html | |
267 | $ rustdoc README.md --html-before-content extra.html | |
268 | ``` | |
269 | ||
270 | This flag takes a list of files, and inserts them inside the `<body>` tag but | |
abe05a73 | 271 | before the other content `rustdoc` would normally produce in the rendered |
041b39d2 XL |
272 | documentation. |
273 | ||
274 | ## `--html-after-content`: include more HTML after the content | |
275 | ||
276 | Using this flag looks like this: | |
277 | ||
278 | ```bash | |
279 | $ rustdoc src/lib.rs --html-after-content extra.html | |
280 | $ rustdoc README.md --html-after-content extra.html | |
281 | ``` | |
282 | ||
283 | This flag takes a list of files, and inserts them before the `</body>` tag but | |
abe05a73 | 284 | after the other content `rustdoc` would normally produce in the rendered |
041b39d2 XL |
285 | documentation. |
286 | ||
287 | ||
288 | ## `--markdown-playground-url`: control the location of the playground | |
289 | ||
290 | Using this flag looks like this: | |
291 | ||
292 | ```bash | |
293 | $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/ | |
294 | ``` | |
295 | ||
296 | When rendering a Markdown file, this flag gives the base URL of the Rust | |
ff7c6d11 | 297 | Playground, to use for generating `Run` buttons. |
041b39d2 XL |
298 | |
299 | ||
300 | ## `--markdown-no-toc`: don't generate a table of contents | |
301 | ||
302 | Using this flag looks like this: | |
303 | ||
304 | ```bash | |
305 | $ rustdoc README.md --markdown-no-toc | |
306 | ``` | |
307 | ||
308 | When generating documentation from a Markdown file, by default, `rustdoc` will | |
ff7c6d11 | 309 | generate a table of contents. This flag suppresses that, and no TOC will be |
041b39d2 XL |
310 | generated. |
311 | ||
312 | ||
313 | ## `-e`/`--extend-css`: extend rustdoc's CSS | |
314 | ||
315 | Using this flag looks like this: | |
316 | ||
317 | ```bash | |
318 | $ rustdoc src/lib.rs -e extra.css | |
319 | $ rustdoc src/lib.rs --extend-css extra.css | |
320 | ``` | |
321 | ||
322 | With this flag, the contents of the files you pass are included at the bottom | |
323 | of Rustdoc's `theme.css` file. | |
324 | ||
325 | While this flag is stable, the contents of `theme.css` are not, so be careful! | |
326 | Updates may break your theme extensions. | |
327 | ||
328 | ## `--sysroot`: override the system root | |
329 | ||
330 | Using this flag looks like this: | |
331 | ||
332 | ```bash | |
333 | $ rustdoc src/lib.rs --sysroot /path/to/sysroot | |
334 | ``` | |
335 | ||
336 | Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses | |
3b2f2976 | 337 | when compiling your code. |
0bf4aa26 XL |
338 | |
339 | ### `--edition`: control the edition of docs and doctests | |
340 | ||
341 | Using this flag looks like this: | |
342 | ||
343 | ```bash | |
344 | $ rustdoc src/lib.rs --edition 2018 | |
345 | $ rustdoc --test src/lib.rs --edition 2018 | |
346 | ``` | |
347 | ||
60c5eb7d | 348 | This flag allows `rustdoc` to treat your rust code as the given edition. It will compile doctests with |
0bf4aa26 XL |
349 | the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015` |
350 | (the first edition). | |
351 | ||
60c5eb7d XL |
352 | ## `--theme`: add a theme to the documentation output |
353 | ||
354 | Using this flag looks like this: | |
355 | ||
356 | ```bash | |
357 | $ rustdoc src/lib.rs --theme /path/to/your/custom-theme.css | |
358 | ``` | |
359 | ||
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. | |
365 | ||
366 | ## `--check-theme`: verify custom themes against the default theme | |
367 | ||
368 | Using this flag looks like this: | |
369 | ||
370 | ```bash | |
371 | $ rustdoc --check-theme /path/to/your/custom-theme.css | |
372 | ``` | |
373 | ||
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. | |
379 | ||
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. | |
ba9703b0 XL |
383 | |
384 | ### `--crate-version`: control the crate version | |
385 | ||
386 | Using this flag looks like this: | |
387 | ||
388 | ```bash | |
389 | $ rustdoc src/lib.rs --crate-version 1.3.37 | |
390 | ``` | |
391 | ||
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. | |
6a06907d XL |
395 | |
396 | ## `@path`: load command-line flags from a path | |
397 | ||
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 | |
401 | encoded as UTF-8. | |
402 | ||
403 | ## `--passes`: add more rustdoc passes | |
404 | ||
405 | This flag is **deprecated**. | |
406 | For more details on passes, see [the chapter on them](passes.md). | |
407 | ||
408 | ## `--no-defaults`: don't run default passes | |
409 | ||
410 | This flag is **deprecated**. | |
411 | For more details on passes, see [the chapter on them](passes.md). | |
412 | ||
413 | ## `-r`/`--input-format`: input format | |
414 | ||
415 | This flag is **deprecated** and **has no effect**. | |
416 | ||
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. |