-
Notifications
You must be signed in to change notification settings - Fork 12.6k
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 and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Stabilize custom_code_classes_in_docs
feature
#124577
Stabilize custom_code_classes_in_docs
feature
#124577
Conversation
This comment has been minimized.
This comment has been minimized.
23d200e
to
f2118b8
Compare
Wow, didn't pay attention but that's a lot of removed lines. :D |
This comment has been minimized.
This comment has been minimized.
f2118b8
to
2f6abd1
Compare
Ok this is ready for review now. |
@rfcbot fcp merge |
This comment was marked as resolved.
This comment was marked as resolved.
Hum, why is the compiler team part of this? Because of the feature in the compiler source maybe? |
@rfcbot fcp cancel Autotagged. I don't think the compiler team needs to participate in this. |
@compiler-errors proposal cancelled. |
Please start a new one @GuillaumeGomez or @notriddle |
Oh it's based on PR's tags and not the source code. Noted. Thanks compiler-errors! @rfcbot fcp merge |
Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members: Concerns:
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. |
Do you mind posting a brief summary of the feature as it currently stands? It seems there was a lot of back-and-forth over things like syntax in the implementation PR. |
🔔 This is now entering its final comment period, as per the review above. 🔔 |
The final comment period, with a disposition to merge, as per the review above, is now complete. As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed. This will be merged soon. |
@bors r=rustdoc |
…de_classes_in_docs, r=rustdoc Stabilize `custom_code_classes_in_docs` feature Fixes rust-lang#79483. This feature has been around for quite some time now, I think it's fine to stabilize it now. ## Summary ## What is the feature about? In short, this PR changes two things, both related to codeblocks in doc comments in Rust documentation: * Allow to disable generation of `language-*` CSS classes with the `custom` attribute. * Add your own CSS classes to a code block so that you can use other tools to highlight them. #### The `custom` attribute Let's start with the new `custom` attribute: it will disable the generation of the `language-*` CSS class on the generated HTML code block. For example: ```rust /// ```custom,c /// int main(void) { /// return 0; /// } /// ``` ``` The generated HTML code block will not have `class="language-c"` because the `custom` attribute has been set. The `custom` attribute becomes especially useful with the other thing added by this feature: adding your own CSS classes. #### Adding your own CSS classes The second part of this feature is to allow users to add CSS classes themselves so that they can then add a JS library which will do it (like `highlight.js` or `prism.js`), allowing to support highlighting for other languages than Rust without increasing burden on rustdoc. To disable the automatic `language-*` CSS class generation, you need to use the `custom` attribute as well. This allow users to write the following: ```rust /// Some code block with `{class=language-c}` as the language string. /// /// ```custom,{class=language-c} /// int main(void) { /// return 0; /// } /// ``` fn main() {} ``` This will notably produce the following HTML: ```html <pre class="language-c"> int main(void) { return 0; }</pre> ``` Instead of: ```html <pre class="rust rust-example-rendered"> <span class="ident">int</span> <span class="ident">main</span>(<span class="ident">void</span>) { <span class="kw">return</span> <span class="number">0</span>; } </pre> ``` To be noted, we could have written `{.language-c}` to achieve the same result. `.` and `class=` have the same effect. One last syntax point: content between parens (`(like this)`) is now considered as comment and is not taken into account at all. In addition to this, I added an `unknown` field into `LangString` (the parsed code block "attribute") because of cases like this: ```rust /// ```custom,class:language-c /// main; /// ``` pub fn foo() {} ``` Without this `unknown` field, it would generate in the DOM: `<pre class="language-class:language-c language-c">`, which is quite bad. So instead, it now stores all unknown tags into the `unknown` field and use the first one as "language". So in this case, since there is no unknown tag, it'll simply generate `<pre class="language-c">`. I added tests to cover this. EDIT(camelid): This description is out-of-date. Using `custom,class:language-c` will generate the output `<pre class="language-class:language-c">` as would be expected; it treats `class:language-c` as just the name of a language (similar to the langstring `c` or `js` or what have you) since it does not use the designed class syntax. Finally, I added a parser for the codeblock attributes to make it much easier to maintain. It'll be pretty easy to extend. As to why this syntax for adding attributes was picked: it's [Pandoc's syntax](https://pandoc.org/MANUAL.html#extension-fenced_code_attributes). Even if it seems clunkier in some cases, it's extensible, and most third-party Markdown renderers are smart enough to ignore Pandoc's brace-delimited attributes (from [this comment](rust-lang#110800 (comment))). r? `@notriddle`
…llaumeGomez Rollup of 4 pull requests Successful merges: - rust-lang#124577 (Stabilize `custom_code_classes_in_docs` feature) - rust-lang#125683 (Rewrite `suspicious-library`, `resolve-rename` and `incr-prev-body-beyond-eof` `run-make` tests in `rmake.rs` format) - rust-lang#125773 (Migrate run make cdylib) - rust-lang#125808 (Migrate `run-make/c-link-to-rust-dylib` to `rmake.rs`) r? `@ghost` `@rustbot` modify labels: rollup
☀️ Test successful - checks-actions |
Finished benchmarking commit (05965ae): comparison URL. Overall result: ✅ improvements - no action needed@rustbot label: -perf-regression Instruction countThis is a highly reliable metric that was used to determine the overall result at the top of this comment.
Max RSS (memory usage)Results (primary 1.4%)This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
CyclesResults (secondary 2.9%)This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
Binary sizeThis benchmark run did not return any relevant results for this metric. Bootstrap: 668.037s -> 668.888s (0.13%) |
This PR seems to have caused a regression (or at least a possibly unexpected behaviour change) that affects a large-ish number of crates - previously, code block attributes that were not recognized as "rust code" in some way were ignored and not compiled, but now "invalid" code block attributes raise a new rustdoc warning lint, but are compiled (and run) as Rust code. For example, the code blocks here use https://github.com/servo/rust-cssparser/blob/main/src/lib.rs#L44-L64 I noticed this because the CI we have for Fedora packages started to turn red for 2-3 dozen Rust crates after Rust 1.80 landed a few days ago. Was this behaviour change intentional? While I agree that it is likely a good idea to warn on "invalid" or unrecognized code block attributes, attempting to compile + run code blocks with unrecognized attributes might not be. |
…-not-rust, r=GuillaumeGomez rustdoc: do not run doctests with invalid langstrings rust-lang#124577 (comment) CC `@decathorpe`
…-not-rust, r=GuillaumeGomez rustdoc: do not run doctests with invalid langstrings rust-lang#124577 (comment) CC ``@decathorpe``
Rollup merge of rust-lang#128838 - notriddle:notriddle/invalid-tag-is-not-rust, r=GuillaumeGomez rustdoc: do not run doctests with invalid langstrings rust-lang#124577 (comment) CC ``@decathorpe``
Fixes #79483.
This feature has been around for quite some time now, I think it's fine to stabilize it now.
Summary
What is the feature about?
In short, this PR changes two things, both related to codeblocks in doc comments in Rust documentation:
language-*
CSS classes with thecustom
attribute.The
custom
attributeLet's start with the new
custom
attribute: it will disable the generation of thelanguage-*
CSS class on the generated HTML code block. For example:The generated HTML code block will not have
class="language-c"
because thecustom
attribute has been set. Thecustom
attribute becomes especially useful with the other thing added by this feature: adding your own CSS classes.Adding your own CSS classes
The second part of this feature is to allow users to add CSS classes themselves so that they can then add a JS library which will do it (like
highlight.js
orprism.js
), allowing to support highlighting for other languages than Rust without increasing burden on rustdoc. To disable the automaticlanguage-*
CSS class generation, you need to use thecustom
attribute as well.This allow users to write the following:
This will notably produce the following HTML:
Instead of:
To be noted, we could have written
{.language-c}
to achieve the same result..
andclass=
have the same effect.One last syntax point: content between parens (
(like this)
) is now considered as comment and is not taken into account at all.In addition to this, I added an
unknown
field intoLangString
(the parsed code block "attribute") because of cases like this:Without this
unknown
field, it would generate in the DOM:<pre class="language-class:language-c language-c">
, which is quite bad. So instead, it now stores all unknown tags into theunknown
field and use the first one as "language". So in this case, since there is no unknown tag, it'll simply generate<pre class="language-c">
. I added tests to cover this.EDIT(camelid): This description is out-of-date. Using
custom,class:language-c
will generate the output<pre class="language-class:language-c">
as would be expected; it treatsclass:language-c
as just the name of a language (similar to the langstringc
orjs
or what have you) since it does not use the designed class syntax.Finally, I added a parser for the codeblock attributes to make it much easier to maintain. It'll be pretty easy to extend.
As to why this syntax for adding attributes was picked: it's Pandoc's syntax. Even if it seems clunkier in some cases, it's extensible, and most third-party Markdown renderers are smart enough to ignore Pandoc's brace-delimited attributes (from this comment).
r? @notriddle