Move doc cfg propagation pass before items stripping passes

2025-09-29T16:08:51+00:00

Rework `#[doc(cfg(..))]` checks as distinct pass in rustdoc

2025-05-29T19:50:14+00:00

rustdoc: rewrite stability inheritance as a pass

2024-09-30T21:58:18+00:00

Auto merge of #124577 - GuillaumeGomez:stabilize-custom_code_classes_in_docs, r=rustdoc

2024-06-01T10:18:01+00:00

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

int main(void) {
    return 0;
}

``` Instead of: ```html

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: ```rust /// ```custom,class:language-c /// main; /// ``` pub fn foo() {} ``` Without this `unknown` field, it would generate in the DOM: `

`, 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 ``. I added tests to cover this.

EDIT(camelid): This description is out-of-date. Using `custom,class:language-c` will generate the output `` 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`

Always hide private fields in aliased type

2024-05-11T11:11:46+00:00

Stabilize `custom_code_classes_in_docs` feature

2024-05-01T14:45:27+00:00

Add tests for `custom_code_classes_in_docs` feature

2023-09-15T19:32:28+00:00

Move some rustdoc-ui tests to subdirectories

2023-04-29T16:36:19+00:00

rust/tests/rustdoc-ui/issues/issue-91713.stdout, branch master