Add Ayu theme to rustdoc #71237
Merged
Add Ayu theme to rustdoc #71237
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
src/librustdoc/html/layout.rs
Outdated
| @@ -53,7 +53,8 @@ pub fn render<T: Print, S: Print>( | |||
| <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}rustdoc{suffix}.css\" \ | |||
| id=\"mainThemeStyle\">\ | |||
| {themes}\ | |||
| <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}dark{suffix}.css\">\ | |||
| <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}ayu{suffix}.css\" disabled=\"true\">\ | |||
| <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}dark{suffix}.css\" disabled=\"true\">\ | |||
|
My only concern is that the logo is super difficult to see now. Otherwise everything else looks good! cc @rust-lang/rustdoc |
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
Dylan-DPC-zz
added
the
S-waiting-on-author
I agree, I have the same concern. I think the best course of action here is a quick
The issue of course being that this can't just be added as a general rule in the stylesheet. There are likely many third-party logos that would look horrendous after color inversion. I could add a little JS to the theme switcher to add and remove the filter when changing to / from the ayu theme in the std docs, which seems like the simplest way forward with the current system. However, if you'd rather come up with a more robust solution (light and dark theme logo support in rustdoc) in a future PR, that's fine as well. I don't think anyone stares at the logo in the docs 😄. So, this is another systematic question to answer here. Now that the stylesheets are disabled in such a way that they don't conflict with one another, it is no longer necessary to have every theme match 1:1 rule-wise. (This would result in a lot of unnecessary lines for the ayu theme; I don't need any of the many I'm obviously not familiar with the workflow around here, so I'll let you determine what the best course of action is (perhaps changing the rule check to a warning instead of a hard error?). |
|
I came up with a better idea for resolving the rule-checker issue. Missing rules can be added as empty rules to the bottom of the file, allowing the rule-checker to be kept on as an error in CI and ensuring that the developer has to explicitly state they don't want to do anything for those rules. The minification process can then remove the empty rules from the assets when compiling. |
|
Even if you don't use all the rules, please use all of them and don't create new one. It's exactly because in the past we had a lot of "forgotten" ones that I decided to add this check.
Huuuuuum... I have to admit that I'm not sure what's the best course here. I guess it's fine for the moment. :) (let's avoid adding JS if possible) |
Cldfire
force-pushed
the
rustdoc-ayu-theme
branch
from
bade621
to
c596a49
Compare
|
Okay, I just pushed fixes for the above discussion. I added empty rules for the rules I didn't need to do anything with as discussed above. Note the comment here. There's a bug in the theme checker; this line breaks the parsing of the I was able to fix that issue by changing the At this point I bailed on attempting to fix the bug and decided to just leave a writeup here as fixing it feels out-of-scope for this PR. A couple other things to note:
|
|
We also need to make sure we're able to include this theme from a licensing perspective. As far as I can tell, the repository you've linked is only licensed under MIT, but we need both MIT and Apache, especially for code that we'll be including in pages generated by rustdoc. |
Ah, good point. If the need arises it should be fairly straightforward to get ahold of the relevant people; the file this is based off of has 3 contributors, all of which are very active on Github. |
|
@Mark-Simulacrum Thanks for the CC; yes, we'll need permission to use this under both MIT and Apache-2.0. You may want to start inquiring after that with the contributors. How does this compare with the existing dark theme? Any chance you could provide some side-by-side comparisons that highlight notable differences introduced in this theme? Is this intended as a third theme option, or as a replacement theme? |
|
Pushed a fix for a bug I discovered while taking the below screenshots (I was mixing in the official styles after source pages were rendered which was causing source pages to be missing stylesheets).
Sure:
Ayu differs from the existing dark theme in that:
This is intended as a third theme option. |
|
This looks excellent to me. And thank you for the detailed clarifications and comparisons. This is what I would expect a dark theme to look like, and I think it'd be the most suitable choice for what rust documentation should use when the user's browser indicates a preference for a dark theme. Looking at those screenshots, I do think that comments need a more contrasting color, though. And could you run this through an appropriate accessibility checker to confirm color contrasts? |
|
Could we change Rust logo to orange or brighter color? |
@joshtriplett I'm glad you like it! Personally, I just want to see the theme shipping with rustdoc. Whether or not it's a default is irrelevant to me. I think it'd be best to land the theme, give it some time out in the field, and then open an RFC and discuss the issue if people are interested.
Oh yeah, I totally missed that! I was actually paying very close attention to the accessibility checker in Firefox's devtools as I combed through and put this together, so 95% of everything is meeting AA standards or better (including the comments after the commit I just pushed). I grabbed https://addons.mozilla.org/en-US/firefox/addon/wcag-contrast-checker/ and took a quick perusal around some pages; on the whole I would subjectively say that glancing at the numbers for Ayu vs. the existing dark theme results in a slight win for Ayu. The extension has some false positives, but I manually checked those in devtools and they are good as well. There are a couple of elements that don't quite meet AA that I noticed (line numbers and issue links on stability warnings). Line numbers I would like to avoid making higher-contrast as they distract from the main content and are useless 99% of the time; in the few cases where you do need to check one, it's easy to click on them in the source view or highlight them with the mouse elsewhere (we could also potentially brighten line numbers on hover in the future?). Issue links in stability warnings are not something you need to read, just be able to notice and click on, so I'd say those are fine as well.
@lzutao Orange could potentially work, yes, and I agree that the logo will need improvement. However, I would say that this discussion is out of place for this PR; some sort of theme-dependent logo system needs to be added to rustdoc which needs to be discussed and implemented elsewhere, imo. Anyhow, beyond fixing comments in the previous commit, I also fixed code blocks in headers (before they were orange like inline code; now they are the standard code text color, which is much more pleasant) and fixed attributes in the source pages (I had previously left them styled like comments). Here's a couple more comparison screenshots:
|
|
I had been meaning to open a PR re merging the two doc theming systems (mdBook and rustdoc) but the scope is way too large and I don't even know where I'd create that issue. Thanks for opening this PR! |
|
Ping from Triage: Hi @Cldfire - any updates? |
|
@joelpalmer Yeah! Current status:
The theme itself is ready-to-go from my point of view. |
|
@bors: retry |
|
@Cldfire: 🔑 Insufficient privileges: not in try users |
bors
added
S-waiting-on-bors
Manishearth
added a commit
to Manishearth/rust
that referenced
this pull request
Jul 13, 2020
…aumeGomez Add Ayu theme to rustdoc This is a port of a theme I maintain (https://github.com/Cldfire/ayu-rs) to the native rustdoc theme system. [Ayu](https://github.com/dempfi/ayu) (dark) is a richly-colored dark theme that many people enjoy using across a wide variety of environments. Corresponds to the Ayu theme in [mdBook](https://github.com/rust-lang/mdBook). Some screenshots:      Note that this pull request also makes some small code changes to allow for disabling theme stylesheets, preventing the rules from all the different themes from conflicting with one another. The only stylesheet that is not disabled is `light.css`; the theming system (quite hackily) switches themes by changing the href on this stylesheet and so permanently disabling all the others works perfectly fine.
Manishearth
added a commit
to Manishearth/rust
that referenced
this pull request
Jul 14, 2020
…aumeGomez Add Ayu theme to rustdoc This is a port of a theme I maintain (https://github.com/Cldfire/ayu-rs) to the native rustdoc theme system. [Ayu](https://github.com/dempfi/ayu) (dark) is a richly-colored dark theme that many people enjoy using across a wide variety of environments. Corresponds to the Ayu theme in [mdBook](https://github.com/rust-lang/mdBook). Some screenshots:      Note that this pull request also makes some small code changes to allow for disabling theme stylesheets, preventing the rules from all the different themes from conflicting with one another. The only stylesheet that is not disabled is `light.css`; the theming system (quite hackily) switches themes by changing the href on this stylesheet and so permanently disabling all the others works perfectly fine.
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
Jul 14, 2020
…aumeGomez Add Ayu theme to rustdoc This is a port of a theme I maintain (https://github.com/Cldfire/ayu-rs) to the native rustdoc theme system. [Ayu](https://github.com/dempfi/ayu) (dark) is a richly-colored dark theme that many people enjoy using across a wide variety of environments. Corresponds to the Ayu theme in [mdBook](https://github.com/rust-lang/mdBook). Some screenshots:      Note that this pull request also makes some small code changes to allow for disabling theme stylesheets, preventing the rules from all the different themes from conflicting with one another. The only stylesheet that is not disabled is `light.css`; the theming system (quite hackily) switches themes by changing the href on this stylesheet and so permanently disabling all the others works perfectly fine.
Manishearth
added a commit
to Manishearth/rust
that referenced
this pull request
Jul 14, 2020
…aumeGomez Add Ayu theme to rustdoc This is a port of a theme I maintain (https://github.com/Cldfire/ayu-rs) to the native rustdoc theme system. [Ayu](https://github.com/dempfi/ayu) (dark) is a richly-colored dark theme that many people enjoy using across a wide variety of environments. Corresponds to the Ayu theme in [mdBook](https://github.com/rust-lang/mdBook). Some screenshots:      Note that this pull request also makes some small code changes to allow for disabling theme stylesheets, preventing the rules from all the different themes from conflicting with one another. The only stylesheet that is not disabled is `light.css`; the theming system (quite hackily) switches themes by changing the href on this stylesheet and so permanently disabling all the others works perfectly fine.
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Jul 14, 2020
…arth Rollup of 15 pull requests Successful merges: - rust-lang#71237 (Add Ayu theme to rustdoc) - rust-lang#73720 (Clean up E0704 error explanation) - rust-lang#73866 (Obviate #[allow(improper_ctypes_definitions)]) - rust-lang#73965 (typeck: check for infer before type impls trait) - rust-lang#73986 (add (unchecked) indexing methods to raw (and NonNull) slices) - rust-lang#74173 (Detect tuple struct incorrectly used as struct pat) - rust-lang#74220 (Refactor Windows `parse_prefix`) - rust-lang#74227 (Remove an unwrap in layout computation) - rust-lang#74239 (Update llvm-project to latest origin/rustc/10.0-2020-05-05 commit ) - rust-lang#74257 (don't mark linux kernel module targets as a unix environment) - rust-lang#74270 (typeck: report placeholder type error w/out span) - rust-lang#74296 (Clarify the description for rfind) - rust-lang#74310 (Use `ArrayVec` in `SparseBitSet`.) - rust-lang#74316 (Remove unnecessary type hints from Wake internals) - rust-lang#74324 (Update Clippy) Failed merges: r? @ghost
yvt
added a commit
to r3-os/r3
that referenced
this pull request
Jul 31, 2020
This theme was recently added to rustdoc. <rust-lang/rust#71237>
|
Awesome work! I like it much more than the previous dark theme 🙂 💪 |
netbsd-srcmastr
pushed a commit
to NetBSD/pkgsrc
that referenced
this pull request
Nov 13, 2020
Pkgsrc changes:
* Remove patches now integrated upstream, many related to SunOS / Illumos.
* The LLVM fix for powerpc is also now integrated upstream.
* Adapt those patches where the source has moved or parts are integrated.
* The randomness patches no longer applies, and I could not find
where those files went...
* Provide a separate bootstrap for NetBSD/powerpc 9.0, since apparently
the C++ ABI is different from 8.0. Yes, this appears to be specific to
the NetBSD powerpc ports.
Upstream changes:
Version 1.47.0 (2020-10-08)
==========================
Language
--------
- [Closures will now warn when not used.][74869]
Compiler
--------
- [Stabilized the `-C control-flow-guard` codegen option][73893], which enables
[Control Flow Guard][1.47.0-cfg] for Windows platforms, and is ignored on
other platforms.
- [Upgraded to LLVM 11.][73526]
- [Added tier 3\* support for the `thumbv4t-none-eabi` target.][74419]
- [Upgrade the FreeBSD toolchain to version 11.4][75204]
- [`RUST_BACKTRACE`'s output is now more compact.][75048]
\* Refer to Rust's [platform support page][forge-platform-support] for more
information on Rust's tiered platform support.
Libraries
---------
- [`CStr` now implements `Index<RangeFrom<usize>>`.][74021]
- [Traits in `std`/`core` are now implemented for arrays of any length, not just
those of length less than 33.][74060]
- [`ops::RangeFull` and `ops::Range` now implement Default.][73197]
- [`panic::Location` now implements `Copy`, `Clone`, `Eq`, `Hash`, `Ord`,
`PartialEq`, and `PartialOrd`.][73583]
Stabilized APIs
---------------
- [`Ident::new_raw`]
- [`Range::is_empty`]
- [`RangeInclusive::is_empty`]
- [`Result::as_deref`]
- [`Result::as_deref_mut`]
- [`Vec::leak`]
- [`pointer::offset_from`]
- [`f32::TAU`]
- [`f64::TAU`]
The following previously stable APIs have now been made const.
- [The `new` method for all `NonZero` integers.][73858]
- [The `checked_add`,`checked_sub`,`checked_mul`,`checked_neg`, `checked_shl`,
`checked_shr`, `saturating_add`, `saturating_sub`, and `saturating_mul`
methods for all integers.][73858]
- [The `checked_abs`, `saturating_abs`, `saturating_neg`, and `signum` for all
signed integers.][73858]
- [The `is_ascii_alphabetic`, `is_ascii_uppercase`, `is_ascii_lowercase`,
`is_ascii_alphanumeric`, `is_ascii_digit`, `is_ascii_hexdigit`,
`is_ascii_punctuation`, `is_ascii_graphic`, `is_ascii_whitespace`, and
`is_ascii_control` methods for `char` and `u8`.][73858]
Cargo
-----
- [`build-dependencies` are now built with opt-level 0 by default.][cargo/8500]
You can override this by setting the following in your `Cargo.toml`.
```toml
[profile.release.build-override]
opt-level = 3
```
- [`cargo-help` will now display man pages for commands rather just the
`--help` text.][cargo/8456]
- [`cargo-metadata` now emits a `test` field indicating if a target has
tests enabled.][cargo/8478]
- [`workspace.default-members` now respects `workspace.exclude`.][cargo/8485]
- [`cargo-publish` will now use an alternative registry by default if it's the
only registry specified in `package.publish`.][cargo/8571]
Misc
----
- [Added a help button beside Rustdoc's searchbar that explains rustdoc's
type based search.][75366]
- [Added the Ayu theme to rustdoc.][71237]
Compatibility Notes
-------------------
- [Bumped the minimum supported Emscripten version to 1.39.20.][75716]
- [Fixed a regression parsing `{} && false` in tail expressions.][74650]
- [Added changes to how proc-macros are expanded in `macro_rules!` that should
help to preserve more span information.][73084] These changes may cause
compiliation errors if your macro was unhygenic or didn't correctly handle
`Delimiter::None`.
- [Moved support for the CloudABI target to tier 3.][75568]
- [`linux-gnu` targets now require minimum kernel 2.6.32 and glibc 2.11.][74163]
Internal Only
--------
- [Improved default settings for bootstrapping in `x.py`.][73964]
You can read details about this change in the ["Changes to `x.py`
defaults"](https://blog.rust-lang.org/inside-rust/2020/08/30/changes-to-x-py-defaults.html)
post on the Inside Rust blog.
- [Added the `rustc-docs` component.][75560] This allows you to install
and read the documentation for the compiler internal APIs. (Currently only
available for `x86_64-unknown-linux-gnu`.)
[1.47.0-cfg]: https://docs.microsoft.com/en-us/windows/win32/secbp/control-flow-guard
[76980]: rust-lang/rust#76980
[75048]: rust-lang/rust#75048
[74163]: rust-lang/rust#74163
[71237]: rust-lang/rust#71237
[74869]: rust-lang/rust#74869
[73858]: rust-lang/rust#73858
[75716]: rust-lang/rust#75716
[75908]: rust-lang/rust#75908
[75516]: rust-lang/rust#75516
[75560]: rust-lang/rust#75560
[75568]: rust-lang/rust#75568
[75366]: rust-lang/rust#75366
[75204]: rust-lang/rust#75204
[74650]: rust-lang/rust#74650
[74419]: rust-lang/rust#74419
[73964]: rust-lang/rust#73964
[74021]: rust-lang/rust#74021
[74060]: rust-lang/rust#74060
[73893]: rust-lang/rust#73893
[73526]: rust-lang/rust#73526
[73583]: rust-lang/rust#73583
[73084]: rust-lang/rust#73084
[73197]: rust-lang/rust#73197
[72488]: rust-lang/rust#72488
[cargo/8456]: rust-lang/cargo#8456
[cargo/8478]: rust-lang/cargo#8478
[cargo/8485]: rust-lang/cargo#8485
[cargo/8500]: rust-lang/cargo#8500
[cargo/8571]: rust-lang/cargo#8571
[`Ident::new_raw`]: https://doc.rust-lang.org/nightly/proc_macro/struct.Ident.html#method.new_raw
[`Range::is_empty`]: https://doc.rust-lang.org/nightly/std/ops/struct.Range.html#method.is_empty
[`RangeInclusive::is_empty`]: https://doc.rust-lang.org/nightly/std/ops/struct.RangeInclusive.html#method.is_empty
[`Result::as_deref_mut`]: https://doc.rust-lang.org/nightly/std/result/enum.Result.html#method.as_deref_mut
[`Result::as_deref`]: https://doc.rust-lang.org/nightly/std/result/enum.Result.html#method.as_deref
[`TypeId::of`]: https://doc.rust-lang.org/nightly/std/any/struct.TypeId.html#method.of
[`Vec::leak`]: https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html#method.leak
[`f32::TAU`]: https://doc.rust-lang.org/nightly/std/f32/consts/constant.TAU.html
[`f64::TAU`]: https://doc.rust-lang.org/nightly/std/f64/consts/constant.TAU.html
[`pointer::offset_from`]: https://doc.rust-lang.org/nightly/std/primitive.pointer.html#method.offset_from
jonathanpallant
added a commit
to ferrocene/rust
that referenced
this pull request
Dec 11, 2023
See rust-lang#71237 for more details.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a port of a theme I maintain (https://github.com/Cldfire/ayu-rs) to the native rustdoc theme system. Ayu (dark) is a richly-colored dark theme that many people enjoy using across a wide variety of environments.
Corresponds to the Ayu theme in mdBook.
Some screenshots:
Note that this pull request also makes some small code changes to allow for disabling theme stylesheets, preventing the rules from all the different themes from conflicting with one another. The only stylesheet that is not disabled is
light.css; the theming system (quite hackily) switches themes by changing the href on this stylesheet and so permanently disabling all the others works perfectly fine.