mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improve error messages and documentation

Browse Source
This commit is contained in:
Guillaume Gomez 2019-10-17 14:26:21 +02:00
parent b004a50f73
commit 71c7dace89
2 changed files with 24 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
src/doc/rustdoc/src/command-line-arguments.md
View File

@ -359,26 +359,34 @@ This flag allows `rustdoc` to treat your rust code as the given edition. It will
the given edition as well. As with `rustc`, the default edition that `rustdoc` will use is `2015`
(the first edition).
## `theme`: add more themes to generated documentation
## `--theme`: add a theme to the documentation output
By default, `rustdoc` only provides the "dark" and "light" themes. If you want to add new ones,
you'll need to use this flag as follows:
Using this flag looks like this:
```bash
$ rustdoc src/lib.rs --theme /path/to/your/theme/file.css
$ rustdoc src/lib.rs --theme /path/to/your/custom-theme.css
```
Note that the theme's name will be the file name without its extension. So if you pass
`/path/to/your/theme/file.css` as theme, then the theme's name will be `file`.
`rustdoc`'s default output includes two themes: `light` (the default) and
`dark`. This flag allows you to add custom themes to the output. Giving a CSS
file to this flag adds it to your documentation as an additional theme choice.
The theme's name is determined by its filename; a theme file named
`custom-theme.css` will add a theme named `custom-theme` to the documentation.
### `check-theme`: check if your themes implement all the required rules
## `--check-theme`: verify custom themes against the default theme
This flag allows you to check if your themes implement the necessary CSS rules. To put it more
simply, when adding a new theme, it needs to implement all the CSS rules present in the "light"
CSS theme.
You can use this flag like this:
Using this flag looks like this:
```bash
$ rustdoc --check-theme /path/to/your/theme/file.css
$ rustdoc --check-theme /path/to/your/custom-theme.css
```
While `rustdoc`'s HTML output is more-or-less consistent between versions, there
is no guarantee that a theme file will have the same effect. The `--theme` flag
will still allow you to add the theme to your documentation, but to ensure that
your theme works as expected, you can use this flag to verify that it implements
the same CSS rules as the official `light` theme.
`--check-theme` is a separate mode in `rustdoc`. When `rustdoc` sees the
`--check-theme` flag, it discards all other flags and only performs the CSS rule
comparison operation.

6
src/librustdoc/config.rs
View File

@ -365,13 +365,13 @@ impl Options {
.iter()
.map(|s| (PathBuf::from(&s), s.to_owned())) {
if !theme_file.is_file() {
diag.struct_err(&format!("invalid file: \"{}\"", theme_s))
.help("option --theme arguments must all be files")
diag.struct_err(&format!("invalid argument: \"{}\"", theme_s))
.help("arguments to --theme must be files")
.emit();
return Err(1);
}
if theme_file.extension() != Some(OsStr::new("css")) {
diag.struct_err(&format!("invalid file: \"{}\": expected CSS file", theme_s))
diag.struct_err(&format!("invalid argument: \"{}\"", theme_s))
.emit();
return Err(1);
}