src/doc/rustdoc/src/command-line-arguments.md

   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
  60 ## `-r`/`--input-format`: input format
  61
  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.
  64
  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.
  68
  69
  70 ## `-w`/`--output-format`: output format
  71
  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.
  74
  75 Rustdoc only supports HTML output, and so this flag is redundant today.
  76
  77 ## `-o`/`--output`: output path
  78
  79 Using this flag looks like this:
  80
  81 ```bash
  82 $ rustdoc src/lib.rs -o target\\doc
  83 $ rustdoc src/lib.rs --output target\\doc
  84 ```
  85
  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.
  89
  90
  91 ## `--crate-name`: controlling the name of the crate
  92
  93 Using this flag looks like this:
  94
  95 ```bash
  96 $ rustdoc src/lib.rs --crate-name mycrate
  97 ```
  98
  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.
 102
 103 ## `-L`/`--library-path`: where to look for dependencies
 104
 105 Using this flag looks like this:
 106
 107 ```bash
 108 $ rustdoc src/lib.rs -L target/debug/deps
 109 $ rustdoc src/lib.rs --library-path target/debug/deps
 110 ```
 111
 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
 114 dependencies.
 115
 116 This flag takes any number of directories as its argument, and will use all of
 117 them when searching.
 118
 119
 120 ## `--cfg`: passing configuration flags
 121
 122 Using this flag looks like this:
 123
 124 ```bash
 125 $ rustdoc src/lib.rs --cfg feature="foo"
 126 ```
 127
 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
 130 are acceptable.
 131
 132 ## `--extern`: specify a dependency's location
 133
 134 Using this flag looks like this:
 135
 136 ```bash
 137 $ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static
 138 ```
 139
 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.
 143
 144 ## `-C`/`--codegen`: pass codegen options to rustc
 145
 146 Using this flag looks like this:
 147
 148 ```bash
 149 $ rustdoc src/lib.rs -C target_feature=+avx
 150 $ rustdoc src/lib.rs --codegen target_feature=+avx
 151
 152 $ rustdoc --test src/lib.rs -C target_feature=+avx
 153 $ rustdoc --test src/lib.rs --codegen target_feature=+avx
 154
 155 $ rustdoc --test README.md -C target_feature=+avx
 156 $ rustdoc --test README.md --codegen target_feature=+avx
 157 ```
 158
 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
 164 affect that.
 165
 166 The arguments to this flag are the same as those for the `-C` flag on rustc. Run `rustc -C help` to
 167 get the full list.
 168
 169 ## `--passes`: add more rustdoc passes
 170
 171 Using this flag looks like this:
 172
 173 ```bash
 174 $ rustdoc --passes list
 175 $ rustdoc src/lib.rs --passes strip-priv-imports
 176 ```
 177
 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.
 180
 181 For more details on passes, see [the chapter on them](passes.html).
 182
 183 See also `--no-defaults`.
 184
 185 ## `--no-defaults`: don't run default passes
 186
 187 Using this flag looks like this:
 188
 189 ```bash
 190 $ rustdoc src/lib.rs --no-defaults
 191 ```
 192
 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.
 196
 197 For more details on passes, see [the chapter on them](passes.html).
 198
 199 See also `--passes`.
 200
 201 ## `--test`: run code examples as tests
 202
 203 Using this flag looks like this:
 204
 205 ```bash
 206 $ rustdoc src/lib.rs --test
 207 ```
 208
 209 This flag will run your code examples as tests. For more, see [the chapter
 210 on documentation tests](documentation-tests.html).
 211
 212 See also `--test-args`.
 213
 214 ## `--test-args`: pass options to test runner
 215
 216 Using this flag looks like this:
 217
 218 ```bash
 219 $ rustdoc src/lib.rs --test --test-args ignored
 220 ```
 221
 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.html).
 224
 225 See also `--test`.
 226
 227 ## `--target`: generate documentation for the specified target triple
 228
 229 Using this flag looks like this:
 230
 231 ```bash
 232 $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
 233 ```
 234
 235 Similar to the `--target` flag for `rustc`, this generates documentation
 236 for a target triple that's different than your host triple.
 237
 238 All of the usual caveats of cross-compiling code apply.
 239
 240 ## `--markdown-css`: include more CSS files when rendering markdown
 241
 242 Using this flag looks like this:
 243
 244 ```bash
 245 $ rustdoc README.md --markdown-css foo.css
 246 ```
 247
 248 When rendering Markdown files, this will create a `<link>` element in the
 249 `<head>` section of the generated HTML. For example, with the invocation above,
 250
 251 ```html
 252 <link rel="stylesheet" type="text/css" href="foo.css">
 253 ```
 254
 255 will be added.
 256
 257 When rendering Rust files, this flag is ignored.
 258
 259 ## `--html-in-header`: include more HTML in <head>
 260
 261 Using this flag looks like this:
 262
 263 ```bash
 264 $ rustdoc src/lib.rs --html-in-header header.html
 265 $ rustdoc README.md --html-in-header header.html
 266 ```
 267
 268 This flag takes a list of files, and inserts them into the `<head>` section of
 269 the rendered documentation.
 270
 271 ## `--html-before-content`: include more HTML before the content
 272
 273 Using this flag looks like this:
 274
 275 ```bash
 276 $ rustdoc src/lib.rs --html-before-content extra.html
 277 $ rustdoc README.md --html-before-content extra.html
 278 ```
 279
 280 This flag takes a list of files, and inserts them inside the `<body>` tag but
 281 before the other content `rustdoc` would normally produce in the rendered
 282 documentation.
 283
 284 ## `--html-after-content`: include more HTML after the content
 285
 286 Using this flag looks like this:
 287
 288 ```bash
 289 $ rustdoc src/lib.rs --html-after-content extra.html
 290 $ rustdoc README.md --html-after-content extra.html
 291 ```
 292
 293 This flag takes a list of files, and inserts them before the `</body>` tag but
 294 after the other content `rustdoc` would normally produce in the rendered
 295 documentation.
 296
 297
 298 ## `--markdown-playground-url`: control the location of the playground
 299
 300 Using this flag looks like this:
 301
 302 ```bash
 303 $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
 304 ```
 305
 306 When rendering a Markdown file, this flag gives the base URL of the Rust
 307 Playground, to use for generating `Run` buttons.
 308
 309
 310 ## `--markdown-no-toc`: don't generate a table of contents
 311
 312 Using this flag looks like this:
 313
 314 ```bash
 315 $ rustdoc README.md --markdown-no-toc
 316 ```
 317
 318 When generating documentation from a Markdown file, by default, `rustdoc` will
 319 generate a table of contents. This flag suppresses that, and no TOC will be
 320 generated.
 321
 322
 323 ## `-e`/`--extend-css`: extend rustdoc's CSS
 324
 325 Using this flag looks like this:
 326
 327 ```bash
 328 $ rustdoc src/lib.rs -e extra.css
 329 $ rustdoc src/lib.rs --extend-css extra.css
 330 ```
 331
 332 With this flag, the contents of the files you pass are included at the bottom
 333 of Rustdoc's `theme.css` file.
 334
 335 While this flag is stable, the contents of `theme.css` are not, so be careful!
 336 Updates may break your theme extensions.
 337
 338 ## `--sysroot`: override the system root
 339
 340 Using this flag looks like this:
 341
 342 ```bash
 343 $ rustdoc src/lib.rs --sysroot /path/to/sysroot
 344 ```
 345
 346 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
 347 when compiling your code.
 348
 349 ### `--edition`: control the edition of docs and doctests
 350
 351 Using this flag looks like this:
 352
 353 ```bash
 354 $ rustdoc src/lib.rs --edition 2018
 355 $ rustdoc --test src/lib.rs --edition 2018
 356 ```
 357
 358 This flag allows rustdoc to treat your rust code as the given edition. It will compile doctests with
 359 the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
 360 (the first edition).
 361