improve error messages and documentation · rust-lang/rust@71c7dac (original) (raw)
`` @@ -359,26 +359,34 @@ This flag allows rustdoc to treat your rust code as the given edition. It will
``
359
359
`` the given edition as well. As with rustc, the default edition that rustdoc will use is 2015
``
360
360
`(the first edition).
`
361
361
``
362
``
`` -
theme: add more themes to generated documentation
``
``
362
`` +
--theme: add a theme to the documentation output
``
363
363
``
364
``
`` -
By default, rustdoc only provides the "dark" and "light" themes. If you want to add new ones,
``
365
``
`-
you'll need to use this flag as follows:
`
``
364
`+
Using this flag looks like this:
`
366
365
``
367
366
```` ```bash
`368`
``
`-
$ rustdoc src/lib.rs --theme /path/to/your/theme/file.css
`
``
`367`
`+
$ rustdoc src/lib.rs --theme /path/to/your/custom-theme.css
`
`369`
`368`
```` ```
370
369
``
371
``
`-
Note that the theme's name will be the file name without its extension. So if you pass
`
372
``
`` -
/path/to/your/theme/file.css as theme, then the theme's name will be file.
``
373
``
-
374
``
`` -
check-theme: check if your themes implement all the required rules
``
``
370
`` +
rustdoc's default output includes two themes: light (the default) and
``
``
371
`` +
dark. This flag allows you to add custom themes to the output. Giving a CSS
``
``
372
`+
file to this flag adds it to your documentation as an additional theme choice.
`
``
373
`+
The theme's name is determined by its filename; a theme file named
`
``
374
`` +
custom-theme.css will add a theme named custom-theme to the documentation.
``
375
375
``
376
``
`-
This flag allows you to check if your themes implement the necessary CSS rules. To put it more
`
377
``
`-
simply, when adding a new theme, it needs to implement all the CSS rules present in the "light"
`
378
``
`-
CSS theme.
`
``
376
`` +
--check-theme: verify custom themes against the default theme
``
379
377
``
380
``
`-
You can use this flag like this:
`
``
378
`+
Using this flag looks like this:
`
381
379
``
382
380
```` ```bash
`383`
``
`-
$ rustdoc --check-theme /path/to/your/theme/file.css
`
``
`381`
`+
$ rustdoc --check-theme /path/to/your/custom-theme.css
`
`384`
`382`
```` ```
``
383
+
``
384
`` +
While rustdoc's HTML output is more-or-less consistent between versions, there
``
``
385
`` +
is no guarantee that a theme file will have the same effect. The --theme flag
``
``
386
`+
will still allow you to add the theme to your documentation, but to ensure that
`
``
387
`+
your theme works as expected, you can use this flag to verify that it implements
`
``
388
`` +
the same CSS rules as the official light theme.
``
``
389
+
``
390
`` +
--check-theme is a separate mode in rustdoc. When rustdoc sees the
``
``
391
`` +
--check-theme flag, it discards all other flags and only performs the CSS rule
``
``
392
`+
comparison operation.
`