Stabilize rustdoc theme options

[GuillaumeGomez]

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.)

[rust-highfive]

r? @steveklabnik

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

[QuietMisdreavus]

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]

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

[QuietMisdreavus]

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]

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]

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]

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]

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

[Mark-Simulacrum]

@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]

@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]

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

• @GuillaumeGomez
• @QuietMisdreavus
• @ollie27
• @onur
• @steveklabnik

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]

@rust-lang/docs ping

[frewsxcv]

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]

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]

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

[GuillaumeGomez]

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

[QuietMisdreavus]

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]

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]

r? @QuietMisdreavus

[GuillaumeGomez]

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

[GuillaumeGomez]

@bors: r=Dylan-DPC

[bors]

📌 Commit 71c7dac has been approved by Dylan-DPC

[GuillaumeGomez]

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

@bors: r-

[JohnTitor]

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

[ollie27]

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]

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]

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]

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

[emilyalbini]

@bors retry

Try to unstuck bors

[bors]

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

[bors]

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