Stabilize rustdoc theme options by GuillaumeGomez · Pull Request #54733 · rust-lang/rust (original) (raw)

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation127 Commits18 Checks0 Files changed

Conversation

This file contains hidden or 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

[ Show hidden characters]({{ revealButtonHref }})

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

r? @steveklabnik

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

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

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

Centril added the relnotes

Marks issues that should be documented in the release notes of the next release.

label

Oct 6, 2018

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.

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?

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.

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.

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

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

@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

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?

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.

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

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

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.

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

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

📌 Commit 71c7dac has been approved by Dylan-DPC

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

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

@bors: r-

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

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

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:

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

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

needs to be:

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

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

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

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 retry

Try to unstuck bors

bors added a commit that referenced this pull request

Nov 18, 2019

…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 mentioned this pull request

Nov 18, 2019

netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this pull request

Feb 17, 2020

Version 1.41.0 (2020-01-30)

Language

• You can now pass type parameters to foreign items when implementing traits. E.g. You can now write impl<T> From<Foo> for Vec<T> {}.
• You can now arbitrarily nest receiver types in the self position. 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. Previously identifiers starting with an underscore were not allowed.
• Visibility modifiers (e.g. pub) are now syntactically allowed on trait items and enum variants. 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 'labels.
• Removed support for the i686-unknown-dragonfly target.
• Added tier 3 support* for the riscv64gc-unknown-linux-gnu target.
• You can now pass an arguments file passing the @path syntax to rustc. Note that the format differs somewhat from what is found in other tooling; please see the documentation 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.

* Refer to Rust's [platform support page][forge-platform-support] for more information on Rust's tiered platform support.

Libraries

• The core::panic module is now stable. It was already stable through std.
• NonZero* numerics now implement From<NonZero*> if it's a smaller integer width. E.g. NonZeroU16 now implements From<NonZeroU8>.
• MaybeUninit<T> now implements fmt::Debug.

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-install will now reinstall the package if it detects that it is out of date.
• Cargo.lock now uses a more git friendly format that should help to reduce merge conflicts.
• You can now override specific dependencies's build settings 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. 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.
• You can use #[cfg(doc)] to compile an item when building documentation.

Compatibility Notes

• As previously announced 1.41.0 will be the last tier 1 release for 32-bit Apple targets. 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.

Labels

disposition-merge

This issue / PR is in PFCP or FCP with a disposition to merge it.

finished-final-comment-period

The final comment period is finished for this PR / Issue.

merged-by-bors

This PR was explicitly merged by bors.

relnotes

Marks issues that should be documented in the release notes of the next release.

S-waiting-on-bors

Status: Waiting on bors to run and complete tests. Bors will change the label on completion.

T-rustdoc

Relevant to the rustdoc team, which will review and decide on the PR/issue.