Stabilize rustdoc theme options #54733

GuillaumeGomez · 2018-10-01T22:43:48Z

This PR stabilizes the --themes (now --theme) and --theme-checker (now --check-theme) options, for allowing users to add custom themes to their documentation.

Rustdoc includes two themes by default: light and dark. Using the --theme option, you can give rustdoc a CSS file to include as an extra theme for that render. Themes are named after the CSS file used, so using --theme /path/to/your/custom-theme.css will add a theme called custom-theme to the documentation.

Even though the CLI flag to add a theme is getting stabilized, there's no guarantee that a theme file will always have the same effect on documentation generated with future versions of rustdoc. To aid in ensuring that a theme will work, the flag --check-theme is also available, which compares the CSS rules defined by a custom theme against the ones used in the light theme. If the light theme defines a CSS rule that the custom theme does not, rustdoc will report an error. (Rustdoc also performs this check for themes given to --theme, but only reports a warning when a difference is found.)

rust-highfive · 2018-10-01T22:43:51Z

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

QuietMisdreavus · 2018-10-04T20:28:48Z

Have these options received any use? Why are we stabilizing them now other than "it's been a few months"?

(For context: this was initially merged back in January.)

GuillaumeGomez · 2018-10-05T09:25:00Z

I have the use of them for some libraries of mine. That'd be nice be able to leave nightly for once. :)

QuietMisdreavus · 2018-10-09T14:19:31Z

In that case, do these options have any tests? I'd like to make sure that, for example, an incomplete theme gets rejected by both --theme and --theme-checker, and that a complete theme gets added to the theme picker. (These may need to be run-make tests? I'm not sure how the working directory is set when resolving arguments given to compiletest. It may be necessary to figure out how to call htmldocck.py to parse the output, or to find some other means to scan the output to make sure the theme is selected.)

This also brings up the conversation we had back when this was merged, about what kind of stability guarantees we have about it. If we have a test for "good theme gets accepted and shown on the page", then that test will break every time we add new rules to the theme CSS. I guess this is to be expected, since it would already happen if you changed light.css without changing dark.css.

GuillaumeGomez · 2018-10-09T15:57:48Z

Do you want to wait for UI tests to be merged first (and we should really try to set it up as soon as possible, too much issues are coming from this lack of test!)? We can add tests the theme-checker as well (testing the test is important too 😛). Does that seem acceptable to you?

QuietMisdreavus · 2018-10-09T21:44:37Z

I don't think we need to wait for the UI tests to ensure the CLI flags work as necessary - the tests it can add are orthogonal to the ones i suggested. I feel like the only thing it can add is to make sure that no unexpected changes happen to the HTML that invalidate a CSS rule, but that was already proposed on the UI tests without having to bring custom themes into it.

QuietMisdreavus · 2018-10-17T22:44:42Z

cc @rust-lang/rustdoc for consensus

In addition to the tests that are still outstanding, does this flag have any docs in the Rustdoc Book? We should make sure that stable items have documentation.

bors · 2018-11-05T12:45:37Z

☔ The latest upstream changes (presumably #55515) made this pull request unmergeable. Please resolve the merge conflicts.

Mark-Simulacrum · 2018-11-15T18:34:54Z

@QuietMisdreavus @rust-lang/rustdoc Can we start an FCP to merge here perhaps? I've marked this as waiting on team for the time being.

QuietMisdreavus · 2018-11-15T19:36:01Z

@Mark-Simulacrum This still needs tests and needs to move the docs to the stable page (and now has a merge conflict because it was written before the CLI centralization), but we can at least ping everyone...

@rust-lang/rustdoc This PR proposes to stabilize the --themes and --theme-checker flags, which allow users to add their own themes to a specific set of docs. These were introduced at the same time as the initial dark theme, and have a safeguard to ensure that a theme is covering the same elements as the default "light" theme.

One thing that is not being stabilized, and likely will not ever be stabilized, is the CSS rules themselves, or the semantic tag layout of the docs. This means that themes are able to "break" between versions, as we add or remove things from the default themes. Historically we have never made this promise (and specifically declared the layout perma-unstable in the initial --themes discussion and the discussion around --extend-css), but the fact that it can cause the same doc command with a certain custom theme to break between versions is something to note. (In fact this is partly why i'm hesitant to stabilize this - i'm not aware of anything else that follows this kind of rule.)

@rfcbot fcp merge

@rfcbot concern stability of css rules

rfcbot · 2018-11-15T19:36:01Z

Team member @QuietMisdreavus has proposed to merge this. The next step is review by the rest of the tagged team members:

Concerns:

~~documentation~~ resolved by Stabilize rustdoc theme options #54733 (comment)
~~don't fail when building docs~~ resolved by Stabilize rustdoc theme options #54733 (comment)
~~stability of css rules~~ resolved by Stabilize rustdoc theme options #54733 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

GuillaumeGomez · 2018-11-24T08:46:53Z

@rust-lang/docs ping

frewsxcv · 2018-11-24T12:20:09Z

By “stabilizing” theme options, does that restrict us from changing the style and layout of the rustdoc output in the future?

@GuillaumeGomez Also, what do you hope to achieve by stabilizing it other than you want to use the stable compiler?

frewsxcv · 2018-11-24T12:34:47Z

One thing that is not being stabilized, and likely will not ever be stabilized, is the CSS rules themselves, or the semantic tag layout of the docs.

Ah, missed @QuietMisdreavus’s comment above

After this flag stabilizes, if someone writes their own theme and the rustdoc team changes the layout between releases, their theme is going to silently break for them when they upgrade. Since they were using a stable feature flag of official rust-lang tooling, I'm worried this will cause frustration and distrust between the users and us.

steveklabnik · 2018-11-24T13:37:23Z

Yeah, I'm not sure myself. I can see it both ways. hmm

GuillaumeGomez · 2018-11-25T13:58:57Z

@frewsxcv Just like you said: it's not stabilizing the UI but the UI generator. :)

QuietMisdreavus · 2018-11-30T16:35:50Z

I think @frewsxcv said it best. The more i think about it, the less certain i am about allowing it on stable like this. It doesn't feel useful enough to allow that potential "stable breakage". Any theme a user adds with this option will only be available on the docs that are generated on that run, meaning it's only generally useful if they're generating all their docs locally (and are using a theme that fits their display/vision/etc) or if they're publicly hosting docs for a crate, losing the people who default to using docs.rs to look up crate docs. If docs.rs wants to add a custom theme, the fact that this is unstable doesn't matter, because it's already using nightly-only items (and is official code anyway).

@GuillaumeGomez I'm curious, does the current theme-checker code have a way to make sure the light theme isn't missing rules that the dark theme is adding? As far as i know, the default theme-checker only tests the other way around.

GuillaumeGomez · 2018-12-01T00:26:11Z

It's a bit subtle (and a bit more simple): each theme is required to implement the same rules. If the dark theme adds new rules that aren't in the light one, then it'll break (since they're not identical anymore).

steveklabnik · 2019-01-18T19:08:52Z

r? @QuietMisdreavus

GuillaumeGomez · 2019-11-18T15:45:41Z

I wonder if the issue isn't simply that I didn't rebase since a long time... Let's retry with a rebase. :)

GuillaumeGomez · 2019-11-18T15:46:06Z

@bors: r=Dylan-DPC

bors · 2019-11-18T15:46:07Z

📌 Commit 71c7dac has been approved by Dylan-DPC

GuillaumeGomez · 2019-11-18T15:50:36Z

We had a redundant HTML check. Let's see if it works better without it (waiting for CI).

@bors: r-

JohnTitor · 2019-11-18T15:59:36Z

IIRC bors checks the PRs with auto merge so rebase is unrelated?

ollie27 · 2019-11-18T16:01:34Z

The $(HTMLDOCCK) is certainly not redundant. It looks like the issue is from shell escaping. ~~I think the solution is to change $(PYTHON) to '$(PYTHON)' here:~~

rust/src/test/run-make-fulldeps/tools.mk

Line 18 in a0d40f8

HTMLDOCCK := $(PYTHON) $(S)/src/etc/htmldocck.py

EDIT: actually I don't think that'll work, I'll try to test locally.

ollie27 · 2019-11-18T16:32:55Z

Okay, I've tested locally and I was half right. You need to put quotes around the path to htmldocck.py as well. So

rust/src/test/run-make-fulldeps/tools.mk

Line 18 in a0d40f8

HTMLDOCCK := $(PYTHON) $(S)/src/etc/htmldocck.py

needs to be:

HTMLDOCCK := '$(PYTHON)' '$(S)/src/etc/htmldocck.py'

GuillaumeGomez · 2019-11-18T17:55:01Z

Ok, applied your changes @ollie27.

Since the CI doesn't seem to check it outside of the bors run, then let's just try again if the shell fix worked!

@bors: r=ollie27,Dylan-DPC

bors · 2019-11-18T17:55:03Z

📌 Commit 45b83c9 has been approved by ollie27,Dylan-DPC

pietroalbini · 2019-11-18T19:03:15Z

@bors retry

Try to unstuck bors

bors · 2019-11-18T19:03:27Z

⌛ Testing commit 45b83c9 with merge 3e525e3...

…e27,Dylan-DPC Stabilize rustdoc theme options Closes #54730 This PR stabilizes the `--themes` (now `--theme`) and `--theme-checker` (now `--check-theme`) options, for allowing users to add custom themes to their documentation. Rustdoc includes two themes by default: `light` and `dark`. Using the `--theme` option, you can give rustdoc a CSS file to include as an extra theme for that render. Themes are named after the CSS file used, so using `--theme /path/to/your/custom-theme.css` will add a theme called `custom-theme` to the documentation. Even though the CLI flag to add a theme is getting stabilized, there's no guarantee that a theme file will always have the same effect on documentation generated with future versions of rustdoc. To aid in ensuring that a theme will work, the flag `--check-theme` is also available, which compares the CSS rules defined by a custom theme against the ones used in the `light` theme. If the `light` theme defines a CSS rule that the custom theme does not, rustdoc will report an error. (Rustdoc also performs this check for themes given to `--theme`, but only reports a warning when a difference is found.)

bors · 2019-11-18T22:08:23Z

☀️ Test successful - checks-azure
Approved by: ollie27,Dylan-DPC
Pushing 3e525e3 to master...

Version 1.41.0 (2020-01-30) =========================== Language -------- - [You can now pass type parameters to foreign items when implementing traits.][65879] E.g. You can now write `impl<T> From<Foo> for Vec<T> {}`. - [You can now arbitrarily nest receiver types in the `self` position.][64325] E.g. you can now write `fn foo(self: Box<Box<Self>>) {}`. Previously only `Self`, `&Self`, `&mut Self`, `Arc<Self>`, `Rc<Self>`, and `Box<Self>` were allowed. - [You can now use any valid identifier in a `format_args` macro.][66847] Previously identifiers starting with an underscore were not allowed. - [Visibility modifiers (e.g. `pub`) are now syntactically allowed on trait items and enum variants.][66183] These are still rejected semantically, but can be seen and parsed by procedural macros and conditional compilation. Compiler -------- - [Rustc will now warn if you have unused loop `'label`s.][66325] - [Removed support for the `i686-unknown-dragonfly` target.][67255] - [Added tier 3 support\* for the `riscv64gc-unknown-linux-gnu` target.][66661] - [You can now pass an arguments file passing the `@path` syntax to rustc.][66172] Note that the format differs somewhat from what is found in other tooling; please see [the documentation][argfile-docs] for more information. - [You can now provide `--extern` flag without a path, indicating that it is available from the search path or specified with an `-L` flag.][64882] \* Refer to Rust's [platform support page][forge-platform-support] for more information on Rust's tiered platform support. [argfile-docs]: https://doc.rust-lang.org/nightly/rustc/command-line-arguments.html#path-load-command-line-flags-from-a-path Libraries --------- - [The `core::panic` module is now stable.][66771] It was already stable through `std`. - [`NonZero*` numerics now implement `From<NonZero*>` if it's a smaller integer width.][66277] E.g. `NonZeroU16` now implements `From<NonZeroU8>`. - [`MaybeUninit<T>` now implements `fmt::Debug`.][65013] Stabilized APIs --------------- - [`Result::map_or`] - [`Result::map_or_else`] - [`std::rc::Weak::weak_count`] - [`std::rc::Weak::strong_count`] - [`std::sync::Weak::weak_count`] - [`std::sync::Weak::strong_count`] Cargo ----- - [Cargo will now document all the private items for binary crates by default.][cargo/7593] - [`cargo-install` will now reinstall the package if it detects that it is out of date.][cargo/7560] - [Cargo.lock now uses a more git friendly format that should help to reduce merge conflicts.][cargo/7579] - [You can now override specific dependencies's build settings][cargo/7591] E.g. `[profile.dev.overrides.image] opt-level = 2` sets the `image` crate's optimisation level to `2` for debug builds. You can also use `[profile.<profile>.build_overrides]` to override build scripts and their dependencies. Misc ---- - [You can now specify `edition` in documentation code blocks to compile the block for that edition.][66238] E.g. `edition2018` tells rustdoc that the code sample should be compiled the 2018 edition of Rust. - [You can now provide custom themes to rustdoc with `--theme`, and check the current theme with `--check-theme`.][54733] - [You can use `#[cfg(doc)]` to compile an item when building documentation.][61351] Compatibility Notes ------------------- - [As previously announced 1.41.0 will be the last tier 1 release for 32-bit Apple targets.][apple-32bit-drop] This means that the source code is still available to build, but the targets are no longer being tested and release binaries for those platforms will no longer be distributed by the Rust project. Please refer to the linked blog post for more information. [54733]: rust-lang/rust#54733 [61351]: rust-lang/rust#61351 [67255]: rust-lang/rust#67255 [66661]: rust-lang/rust#66661 [66771]: rust-lang/rust#66771 [66847]: rust-lang/rust#66847 [66238]: rust-lang/rust#66238 [66277]: rust-lang/rust#66277 [66325]: rust-lang/rust#66325 [66172]: rust-lang/rust#66172 [66183]: rust-lang/rust#66183 [65879]: rust-lang/rust#65879 [65013]: rust-lang/rust#65013 [64882]: rust-lang/rust#64882 [64325]: rust-lang/rust#64325 [cargo/7560]: rust-lang/cargo#7560 [cargo/7579]: rust-lang/cargo#7579 [cargo/7591]: rust-lang/cargo#7591 [cargo/7593]: rust-lang/cargo#7593 [`Result::map_or_else`]: https://doc.rust-lang.org/std/result/enum.Result.html#method.map_or_else [`Result::map_or`]: https://doc.rust-lang.org/std/result/enum.Result.html#method.map_or [`std::rc::Weak::weak_count`]: https://doc.rust-lang.org/std/rc/struct.Weak.html#method.weak_count [`std::rc::Weak::strong_count`]: https://doc.rust-lang.org/std/rc/struct.Weak.html#method.strong_count [`std::sync::Weak::weak_count`]: https://doc.rust-lang.org/std/sync/struct.Weak.html#method.weak_count [`std::sync::Weak::strong_count`]: https://doc.rust-lang.org/std/sync/struct.Weak.html#method.strong_count [apple-32bit-drop]: https://blog.rust-lang.org/2020/01/03/reducing-support-for-32-bit-apple-targets.html

rust-highfive assigned steveklabnik Oct 1, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 1, 2018

Centril added the relnotes Marks issues that should be documented in the release notes of the next release. label Oct 6, 2018

QuietMisdreavus self-assigned this Oct 17, 2018

QuietMisdreavus added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Oct 26, 2018

Mark-Simulacrum added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 15, 2018

rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Nov 15, 2018

GuillaumeGomez force-pushed the stabilize-rustdoc-theme branch from 1740393 to 478d7e4 Compare November 24, 2018 08:45

rust-highfive unassigned steveklabnik Jan 18, 2019

GuillaumeGomez added 3 commits November 18, 2019 16:43

Apply review comments

530d866

remove -Z option from rustdoc theme checker tool

b004a50

improve error messages and documentation

71c7dac

GuillaumeGomez force-pushed the stabilize-rustdoc-theme branch from 1ebb9ec to 71c7dac Compare November 18, 2019 15:45

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 18, 2019

Remove redundant html check

a9e8d4c

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Nov 18, 2019

Fix Makefile themes check

45b83c9

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Nov 18, 2019

bors added the merged-by-bors This PR was explicitly merged by bors. label Nov 18, 2019

bors merged commit 45b83c9 into rust-lang:master Nov 18, 2019

bors mentioned this pull request Nov 18, 2019

--show-coverage json #66472

Merged

GuillaumeGomez deleted the stabilize-rustdoc-theme branch November 18, 2019 22:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stabilize rustdoc theme options #54733

Stabilize rustdoc theme options #54733

GuillaumeGomez commented Oct 1, 2018 •

edited by QuietMisdreavus

rust-highfive commented Oct 1, 2018

QuietMisdreavus commented Oct 4, 2018

GuillaumeGomez commented Oct 5, 2018

QuietMisdreavus commented Oct 9, 2018

GuillaumeGomez commented Oct 9, 2018

QuietMisdreavus commented Oct 9, 2018

QuietMisdreavus commented Oct 17, 2018

bors commented Nov 5, 2018

Mark-Simulacrum commented Nov 15, 2018

QuietMisdreavus commented Nov 15, 2018

rfcbot commented Nov 15, 2018 •

edited

GuillaumeGomez commented Nov 24, 2018

frewsxcv commented Nov 24, 2018

frewsxcv commented Nov 24, 2018

steveklabnik commented Nov 24, 2018

GuillaumeGomez commented Nov 25, 2018

QuietMisdreavus commented Nov 30, 2018

GuillaumeGomez commented Dec 1, 2018

steveklabnik commented Jan 18, 2019

GuillaumeGomez commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

bors commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

JohnTitor commented Nov 18, 2019

ollie27 commented Nov 18, 2019 •

edited

ollie27 commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

bors commented Nov 18, 2019

pietroalbini commented Nov 18, 2019

bors commented Nov 18, 2019

bors commented Nov 18, 2019

Stabilize rustdoc theme options #54733

Stabilize rustdoc theme options #54733

Conversation

GuillaumeGomez commented Oct 1, 2018 • edited by QuietMisdreavus

rust-highfive commented Oct 1, 2018

QuietMisdreavus commented Oct 4, 2018

GuillaumeGomez commented Oct 5, 2018

QuietMisdreavus commented Oct 9, 2018

GuillaumeGomez commented Oct 9, 2018

QuietMisdreavus commented Oct 9, 2018

QuietMisdreavus commented Oct 17, 2018

bors commented Nov 5, 2018

Mark-Simulacrum commented Nov 15, 2018

QuietMisdreavus commented Nov 15, 2018

rfcbot commented Nov 15, 2018 • edited

GuillaumeGomez commented Nov 24, 2018

frewsxcv commented Nov 24, 2018

frewsxcv commented Nov 24, 2018

steveklabnik commented Nov 24, 2018

GuillaumeGomez commented Nov 25, 2018

QuietMisdreavus commented Nov 30, 2018

GuillaumeGomez commented Dec 1, 2018

steveklabnik commented Jan 18, 2019

GuillaumeGomez commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

bors commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

JohnTitor commented Nov 18, 2019

ollie27 commented Nov 18, 2019 • edited

ollie27 commented Nov 18, 2019

GuillaumeGomez commented Nov 18, 2019

bors commented Nov 18, 2019

pietroalbini commented Nov 18, 2019

bors commented Nov 18, 2019

bors commented Nov 18, 2019

GuillaumeGomez commented Oct 1, 2018 •

edited by QuietMisdreavus

rfcbot commented Nov 15, 2018 •

edited

ollie27 commented Nov 18, 2019 •

edited