From 71c7dace89959e185948e91b902ffb803aa8d223 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 17 Oct 2019 14:26:21 +0200 Subject: [PATCH] improve error messages and documentation --- src/doc/rustdoc/src/command-line-arguments.md | 34 ++++++++++++------- src/librustdoc/config.rs | 6 ++-- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md index 40bd6f43c61..2e32ce31eca 100644 --- a/src/doc/rustdoc/src/command-line-arguments.md +++ b/src/doc/rustdoc/src/command-line-arguments.md @@ -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`. - -### `check-theme`: check if your themes implement all the required rules +`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. -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. +## `--check-theme`: verify custom themes against the default 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. diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index d48416d4177..cdb1a1f6997 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -365,13 +365,13 @@ pub fn from_matches(matches: &getopts::Matches) -> Result { .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); } -- 2.44.0