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 ## `--passes`: add more rustdoc passes
 145
 146 Using this flag looks like this:
 147
 148 ```bash
 149 $ rustdoc --passes list
 150 $ rustdoc src/lib.rs --passes strip-priv-imports
 151 ```
 152
 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.
 155
 156 For more details on passes, see [the chapter on them](passes.html).
 157
 158 See also `--no-defaults`.
 159
 160 ## `--no-defaults`: don't run default passes
 161
 162 Using this flag looks like this:
 163
 164 ```bash
 165 $ rustdoc src/lib.rs --no-defaults
 166 ```
 167
 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.
 171
 172 For more details on passes, see [the chapter on them](passes.html).
 173
 174 See also `--passes`.
 175
 176 ## `--test`: run code examples as tests
 177
 178 Using this flag looks like this:
 179
 180 ```bash
 181 $ rustdoc src/lib.rs --test
 182 ```
 183
 184 This flag will run your code examples as tests. For more, see [the chapter
 185 on documentation tests](documentation-tests.html).
 186
 187 See also `--test-args`.
 188
 189 ## `--test-args`: pass options to test runner
 190
 191 Using this flag looks like this:
 192
 193 ```bash
 194 $ rustdoc src/lib.rs --test --test-args ignored
 195 ```
 196
 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).
 199
 200 See also `--test`.
 201
 202 ## `--target`: generate documentation for the specified target triple
 203
 204 Using this flag looks like this:
 205
 206 ```bash
 207 $ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
 208 ```
 209
 210 Similar to the `--target` flag for `rustc`, this generates documentation
 211 for a target triple that's different than your host triple.
 212
 213 All of the usual caveats of cross-compiling code apply.
 214
 215 ## `--markdown-css`: include more CSS files when rendering markdown
 216
 217 Using this flag looks like this:
 218
 219 ```bash
 220 $ rustdoc README.md --markdown-css foo.css
 221 ```
 222
 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,
 225
 226 ```html
 227 <link rel="stylesheet" type="text/css" href="foo.css">
 228 ```
 229
 230 will be added.
 231
 232 When rendering Rust files, this flag is ignored.
 233
 234 ## `--html-in-header`: include more HTML in <head>
 235
 236 Using this flag looks like this:
 237
 238 ```bash
 239 $ rustdoc src/lib.rs --html-in-header header.html
 240 $ rustdoc README.md --html-in-header header.html
 241 ```
 242
 243 This flag takes a list of files, and inserts them into the `<head>` section of
 244 the rendered documentation.
 245
 246 ## `--html-before-content`: include more HTML before the content
 247
 248 Using this flag looks like this:
 249
 250 ```bash
 251 $ rustdoc src/lib.rs --html-before-content extra.html
 252 $ rustdoc README.md --html-before-content extra.html
 253 ```
 254
 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
 257 documentation.
 258
 259 ## `--html-after-content`: include more HTML after the content
 260
 261 Using this flag looks like this:
 262
 263 ```bash
 264 $ rustdoc src/lib.rs --html-after-content extra.html
 265 $ rustdoc README.md --html-after-content extra.html
 266 ```
 267
 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
 270 documentation.
 271
 272
 273 ## `--markdown-playground-url`: control the location of the playground
 274
 275 Using this flag looks like this:
 276
 277 ```bash
 278 $ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
 279 ```
 280
 281 When rendering a Markdown file, this flag gives the base URL of the Rust
 282 Playground, to use for generating `Run` buttons.
 283
 284
 285 ## `--markdown-no-toc`: don't generate a table of contents
 286
 287 Using this flag looks like this:
 288
 289 ```bash
 290 $ rustdoc README.md --markdown-no-toc
 291 ```
 292
 293 When generating documentation from a Markdown file, by default, `rustdoc` will
 294 generate a table of contents. This flag suppresses that, and no TOC will be
 295 generated.
 296
 297
 298 ## `-e`/`--extend-css`: extend rustdoc's CSS
 299
 300 Using this flag looks like this:
 301
 302 ```bash
 303 $ rustdoc src/lib.rs -e extra.css
 304 $ rustdoc src/lib.rs --extend-css extra.css
 305 ```
 306
 307 With this flag, the contents of the files you pass are included at the bottom
 308 of Rustdoc's `theme.css` file.
 309
 310 While this flag is stable, the contents of `theme.css` are not, so be careful!
 311 Updates may break your theme extensions.
 312
 313 ## `--sysroot`: override the system root
 314
 315 Using this flag looks like this:
 316
 317 ```bash
 318 $ rustdoc src/lib.rs --sysroot /path/to/sysroot
 319 ```
 320
 321 Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
 322 when compiling your code.