Stabilize custom_code_classes_in_docs feature by GuillaumeGomez · Pull Request #124577 · rust-lang/rust (original) (raw)

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:

/// 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:

/// 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:

int main(void) {
    return 0;
}

Instead of:

int main(void) {
    return 0;
}

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:

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