bors
05965ae238
Auto merge of #124577 - GuillaumeGomez:stabilize-custom_code_classes_in_docs, r=rustdoc
...
Stabilize `custom_code_classes_in_docs` feature
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:
* 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](https://github.com/rust-lang/rust/pull/110800#issuecomment-1522044456 )).
r? `@notriddle`
2024-06-01 10:18:01 +00:00
..
2024-05-21 21:21:26 -07:00
2024-02-22 16:04:04 +00:00
2023-11-29 12:10:16 +01:00
2024-02-22 16:04:04 +00:00
2023-01-28 17:18:56 -07:00
2023-06-21 21:53:55 +02:00
2024-05-21 21:21:26 -07:00
2024-05-21 21:21:26 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-05-14 20:40:59 -04:00
2024-04-06 23:47:40 -04:00
2024-05-21 21:21:26 -07:00
2024-02-22 16:04:04 +00:00
2024-02-24 16:47:29 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-10-04 13:04:45 -07:00
2023-09-27 17:22:18 -07:00
2023-10-04 13:04:45 -07:00
2023-07-14 16:38:01 -07:00
2023-07-14 16:38:01 -07:00
2023-07-14 16:38:01 -07:00
2023-07-14 16:38:01 -07:00
2023-07-14 16:38:01 -07:00
2023-04-29 15:36:03 -04:00
2023-07-14 16:38:01 -07:00
2023-03-09 18:08:22 +01:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2024-05-21 12:28:34 -07:00
2023-06-07 13:29:36 +02:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2023-01-30 11:06:18 -07:00
2023-03-30 22:56:52 +02:00
2024-02-29 13:55:11 +00:00
2024-01-03 15:33:12 -07:00
2024-01-03 15:33:12 -07:00
2024-01-03 15:33:12 -07:00
2024-02-22 16:04:04 +00:00
2024-01-03 15:33:12 -07:00
2023-10-16 18:01:02 -07:00
2024-04-15 15:13:05 -07:00
2023-09-21 15:16:44 -07:00
2024-02-16 21:29:16 +01:00
2023-02-07 19:00:42 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-27 09:04:39 -07:00
2024-02-22 16:04:04 +00:00
2023-11-29 13:40:07 -07:00
2024-05-26 21:06:02 -07:00
2023-11-05 00:56:54 +01:00
2024-04-15 15:13:05 -07:00
2023-10-12 16:14:54 +00:00
2023-01-30 11:06:18 -07:00
2023-01-30 11:06:18 -07:00
2023-10-16 18:01:02 -07:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-05-01 16:45:27 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-24 23:39:35 +02:00
2023-06-24 23:39:35 +02:00
2023-10-31 13:58:03 +00:00
2023-10-31 13:58:03 +00:00
2023-10-04 13:04:45 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-24 23:14:57 -04:00
2024-02-22 16:04:04 +00:00
2023-12-05 09:18:41 +01:00
2023-03-20 05:21:51 +00:00
2023-09-27 17:22:18 -07:00
2024-02-22 16:04:04 +00:00
2023-09-27 17:22:18 -07:00
2024-01-03 15:33:12 -07:00
2024-01-03 15:33:12 -07:00
2023-08-18 15:19:18 +08:00
2023-10-16 18:01:02 -07:00
2023-12-05 15:59:40 +01:00
2024-03-14 14:51:01 +01:00
2023-01-28 17:18:56 -07:00
2024-01-03 15:33:12 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-04-15 15:13:05 -07:00
2024-02-22 16:04:04 +00:00
2023-02-07 19:00:42 -07:00
2024-02-22 16:04:04 +00:00
2024-04-15 15:13:05 -07:00
2024-04-15 15:13:05 -07:00
2024-04-15 15:13:05 -07:00
2024-04-15 15:13:05 -07:00
2023-10-16 18:01:02 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-30 19:04:59 +00:00
2023-06-02 13:51:01 +02:00
2023-02-03 17:58:26 -07:00
2023-02-07 19:00:42 -07:00
2024-02-22 16:04:04 +00:00
2023-01-28 17:18:56 -07:00
2024-04-15 15:13:05 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-28 17:18:56 -07:00
2023-01-28 17:18:56 -07:00
2024-02-22 16:04:04 +00:00
2024-02-29 13:55:11 +00:00
2023-11-29 12:10:16 +01:00
2024-05-21 12:28:34 -07:00
2023-12-04 12:13:24 +01:00
2023-12-04 12:13:24 +01:00
2023-11-20 11:50:25 -07:00
2024-01-03 15:33:12 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-10-04 13:04:45 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-23 15:12:48 +02:00
2023-06-23 15:12:48 +02:00
2023-01-30 11:06:18 -07:00
2024-01-29 14:14:03 +01:00
2023-03-19 18:02:52 +01:00
2024-02-22 16:04:04 +00:00
2023-11-20 11:50:25 -07:00
2023-07-28 22:23:21 +02:00
2023-09-21 15:16:44 -07:00
2024-01-30 18:14:09 +01:00
2024-02-01 11:47:02 +01:00
2023-02-07 19:00:42 -07:00
2023-02-07 19:00:42 -07:00
2024-05-21 12:28:34 -07:00
2023-10-16 18:01:02 -07:00
2023-10-22 15:47:34 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-10-31 13:58:03 +00:00
2024-04-15 15:13:05 -07:00
2024-02-22 16:04:04 +00:00
2023-09-27 17:22:18 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-05-10 22:49:05 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-07-26 02:11:35 +02:00
2023-01-27 14:41:33 +01:00
2024-01-20 13:21:03 +01:00
2024-02-22 16:04:04 +00:00
2023-01-28 17:18:56 -07:00
2023-09-27 17:22:18 -07:00
2024-01-03 15:33:12 -07:00
2023-10-16 18:01:02 -07:00
2023-11-29 12:10:16 +01:00
2024-04-15 15:13:05 -07:00
2024-02-22 16:04:04 +00:00
2023-09-27 17:22:18 -07:00
2023-09-27 17:22:18 -07:00
2023-08-03 02:18:52 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-11-29 13:40:07 -07:00
2023-11-20 11:50:25 -07:00
2024-02-22 16:04:04 +00:00
2024-04-15 15:13:05 -07:00
2024-03-05 09:02:33 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-11-29 13:40:07 -07:00
2023-11-29 13:40:07 -07:00
2023-04-27 16:25:05 +08:00
2024-02-24 15:38:55 -07:00
2024-02-24 15:38:55 -07:00
2023-01-27 12:11:01 +01:00
2023-02-18 23:24:58 +01:00
2023-02-20 20:19:21 +01:00
2023-02-21 16:26:06 +01:00
2023-03-07 21:20:21 +01:00
2023-03-27 18:58:07 +00:00
2023-03-09 18:08:22 +01:00
2023-11-29 13:40:07 -07:00
2023-11-29 13:40:07 -07:00
2023-03-29 16:17:48 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-23 15:12:48 +02:00
2023-05-05 21:33:44 +02:00
2023-06-23 15:12:48 +02:00
2024-02-22 16:04:04 +00:00
2023-10-15 18:09:34 +02:00
2023-11-23 16:04:10 +01:00
2023-02-23 13:53:27 -07:00
2023-02-23 13:53:27 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-27 16:20:11 +01:00
2024-02-22 16:04:04 +00:00
2023-01-13 10:09:25 -07:00
2023-01-30 11:06:18 -07:00
2023-01-30 11:06:18 -07:00
2024-03-12 01:25:15 +01:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-12-05 15:59:40 +01:00
2023-01-13 12:38:03 -07:00
2023-10-08 20:17:53 -07:00
2023-12-18 13:56:55 -07:00
2023-12-18 13:56:55 -07:00
2024-02-22 16:04:04 +00:00
2023-10-04 13:04:45 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2023-09-27 17:22:18 -07:00
2024-02-22 16:04:04 +00:00
2024-04-15 15:13:05 -07:00
2023-10-04 13:04:45 -07:00
2024-02-22 16:04:04 +00:00
2024-05-21 12:28:34 -07:00
2024-02-22 16:04:04 +00:00
2023-01-13 12:38:03 -07:00
2024-02-22 16:04:04 +00:00
2023-01-13 12:38:03 -07:00
2024-05-21 12:28:34 -07:00
2024-05-21 12:28:34 -07:00
2024-05-21 12:28:34 -07:00
2023-01-30 11:06:18 -07:00
2023-01-28 17:18:56 -07:00
2023-11-29 13:40:07 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-03-28 16:50:49 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-15 18:57:21 +08:00
2023-09-27 17:22:18 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-03-30 22:56:52 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-09-06 13:26:56 +02:00
2024-05-11 13:11:46 +02:00
2024-05-11 13:11:46 +02:00
2023-11-20 11:50:25 -07:00
2023-07-26 15:29:45 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-11-29 13:40:07 -07:00
2024-02-22 16:04:04 +00:00
2024-05-21 12:28:34 -07:00
2024-01-03 15:33:12 -07:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-03 19:57:17 +02:00
2023-11-22 17:22:29 +01:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-06-26 16:38:14 +02:00
2023-05-26 17:31:54 +02:00
2024-02-22 16:04:04 +00:00
2023-05-27 00:25:37 +02:00
2023-02-10 18:37:32 +01:00
2023-05-27 00:25:37 +02:00
2023-11-22 17:22:30 +01:00
2023-11-22 17:22:30 +01:00
2023-02-22 17:49:22 +01:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-12-05 15:59:40 +01:00
2024-02-22 16:04:04 +00:00
2023-09-18 19:30:10 +02:00
2024-04-28 11:17:09 +08:00
2023-11-30 10:43:40 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2023-10-04 13:04:45 -07:00
2024-03-16 22:07:30 -07:00
2023-02-07 19:00:42 -07:00
2023-12-05 15:59:40 +01:00
2023-09-01 17:22:48 -04:00
2023-08-21 12:53:39 -07:00
2023-10-29 22:57:45 +01:00
2023-09-21 15:16:44 -07:00
2024-04-15 15:13:05 -07:00
2023-01-30 11:06:18 -07:00
2024-01-03 15:33:12 -07:00
2024-02-22 16:04:04 +00:00
2024-02-28 16:08:46 +01:00
2023-07-14 16:54:14 -07:00
2023-10-24 17:34:59 -07:00
2024-02-22 16:04:04 +00:00
2023-09-21 15:16:44 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-11-23 17:20:13 -08:00
2023-10-16 18:01:02 -07:00
2023-10-04 13:04:45 -07:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-13 12:38:03 -07:00
2023-10-22 15:56:14 -07:00
2023-10-22 15:56:14 -07:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2023-10-16 18:01:02 -07:00
2024-01-03 15:33:12 -07:00
2023-10-16 18:01:02 -07:00
2023-03-30 22:56:52 +02:00
2023-01-30 11:06:18 -07:00
2023-05-25 13:27:29 +00:00
2023-10-08 20:17:40 -07:00
2023-01-30 11:06:18 -07:00
2023-01-13 12:38:03 -07:00
2023-01-13 12:38:03 -07:00
2023-01-30 11:06:18 -07:00
2024-02-22 16:04:04 +00:00
2023-11-20 11:50:25 -07:00
2024-03-01 15:33:02 +01:00
2023-12-23 11:28:33 +01:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-01-30 11:06:18 -07:00
2023-11-23 14:54:19 -07:00
2023-01-30 11:06:18 -07:00
2024-02-25 12:03:48 +01:00
2023-11-30 10:43:40 -07:00
2024-05-19 20:13:18 -04:00
2023-01-28 17:18:56 -07:00
2024-04-15 15:13:05 -07:00
2024-05-21 12:28:34 -07:00
2023-06-21 17:42:53 +02:00
2024-02-22 16:04:04 +00:00
2024-02-22 16:04:04 +00:00
2023-10-24 17:34:59 -07:00
2024-02-22 16:04:04 +00:00
2023-10-30 16:44:52 +01:00
2023-01-30 11:06:18 -07:00
2023-12-01 11:35:01 +01:00
2023-11-30 10:43:40 -07:00
2023-11-30 10:43:40 -07:00
2023-11-30 10:43:40 -07:00
2023-09-06 11:16:05 +02:00
2023-11-30 10:43:40 -07:00
2023-12-01 11:35:01 +01:00
2023-02-07 11:23:25 -07:00
2023-10-31 13:58:03 +00:00
2023-11-30 10:43:40 -07:00
2023-10-31 13:58:03 +00:00
2023-10-31 13:58:03 +00:00
2023-11-30 10:43:40 -07:00
2023-02-04 19:10:04 +01:00
2023-11-30 10:43:40 -07:00
2023-12-01 11:35:01 +01:00
2023-12-01 11:35:01 +01:00
2023-01-30 11:06:18 -07:00