mirror of https://github.com/rust-lang/rust.git
05965ae238
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` |
||
|---|---|---|
| .. | ||
| argfile | ||
| auxiliary | ||
| coverage | ||
| doctest | ||
| error-in-impl-trait | ||
| generate-link-to-definition | ||
| intra-doc | ||
| issues | ||
| lints | ||
| scrape-examples | ||
| suggestions | ||
| synthetic-auto-trait-impls | ||
| ambiguous-inherent-assoc-ty.rs | ||
| apit-46976.rs | ||
| bounded-hr-lifetime.rs | ||
| bounded-hr-lifetime.stderr | ||
| check-cfg.rs | ||
| check-cfg.stderr | ||
| check-doc-alias-attr-location.rs | ||
| check-doc-alias-attr-location.stderr | ||
| check-doc-alias-attr.rs | ||
| check-doc-alias-attr.stderr | ||
| circular-intra-doc-link-48414.rs | ||
| const-evalutation-ice.rs | ||
| const-evalutation-ice.stderr | ||
| const_arg_in_type_position.rs | ||
| const_arg_in_type_position.stderr | ||
| crate-reference-in-block-module.rs | ||
| crate-reference-in-block-module.stderr | ||
| custom_code_classes_in_docs-warning3.rs | ||
| custom_code_classes_in_docs-warning3.stderr | ||
| deprecated-attrs.rs | ||
| deprecated-attrs.stderr | ||
| deref-generic.rs | ||
| diagnostic-width.rs | ||
| diagnostic-width.stderr | ||
| doc-alias-assoc-const.rs | ||
| doc-alias-assoc-const.stderr | ||
| doc-alias-crate-level.rs | ||
| doc-alias-crate-level.stderr | ||
| doc-alias-same-name.rs | ||
| doc-alias-same-name.stderr | ||
| doc-cfg.rs | ||
| doc-cfg.stderr | ||
| doc-include-suggestion.rs | ||
| doc-include-suggestion.stderr | ||
| feature-gate-doc_cfg_hide.rs | ||
| feature-gate-doc_cfg_hide.stderr | ||
| hidden-trait-method-34423.rs | ||
| ice-assoc-const-for-primitive-31808.rs | ||
| ice-blanket-impl-52873.rs | ||
| ice-blanket-impl-56701.rs | ||
| ice-blanket-impl-selection-55001.rs | ||
| ice-bug-report-url.rs | ||
| ice-bug-report-url.stderr | ||
| ice-cross-crate-opaque-assoc-type-73061.rs | ||
| ignore-block-help.rs | ||
| ignore-block-help.stderr | ||
| impl-fn-nesting.rs | ||
| impl-fn-nesting.stderr | ||
| include-str-bare-urls.rs | ||
| include-str-bare-urls.stderr | ||
| infinite-recursive-type.rs | ||
| infinite-recursive-type.stderr | ||
| inherent-assoc-consts-36031.rs | ||
| invalid-cfg.rs | ||
| invalid-cfg.stderr | ||
| invalid-keyword.rs | ||
| invalid-keyword.stderr | ||
| invalid-redundant-explicit-link.rs | ||
| invalid-syntax.rs | ||
| invalid-syntax.stderr | ||
| invalid-theme-name.rs | ||
| invalid-theme-name.stderr | ||
| invalid_associated_const.rs | ||
| invalid_associated_const.stderr | ||
| invalid_const_in_lifetime_position.rs | ||
| invalid_const_in_lifetime_position.stderr | ||
| invalid_infered_static_and_const.rs | ||
| invalid_infered_static_and_const.stderr | ||
| issue-102467.rs | ||
| issue-102467.stderr | ||
| issue-110629-private-type-cycle-dyn.rs | ||
| issue-110629-private-type-cycle-dyn.stderr | ||
| issue-110629-private-type-cycle.rs | ||
| macro-docs.rs | ||
| macro-docs.stderr | ||
| macro-docs.stdout | ||
| mismatched_arg_count.rs | ||
| mismatched_arg_count.stderr | ||
| nested-extern-crate-46271.rs | ||
| nested-macro-rules-47639.rs | ||
| normalize-cycle.rs | ||
| normalize-in-inlined-type-alias.rs | ||
| normalize-overflow.rs | ||
| not-wf-ambiguous-normalization.rs | ||
| not-wf-ambiguous-normalization.stderr | ||
| output-format-html-stable.rs | ||
| proc_macro_bug.rs | ||
| proc_macro_bug.stderr | ||
| pub-use-primitive-document-private-items-95633.rs | ||
| range-pattern.rs | ||
| recursive-deref-ice.rs | ||
| redundant-explicit-links-123677.rs | ||
| rustc-check-passes.rs | ||
| rustc-check-passes.stderr | ||
| search-index-generics-recursion-bug-issue-59502.rs | ||
| super-glob-40936.rs | ||
| track-diagnostics.rs | ||
| track-diagnostics.stderr | ||
| tuple-variadic-check.rs | ||
| tuple-variadic-check.stderr | ||
| unable-fulfill-trait.rs | ||
| unable-fulfill-trait.stderr | ||
| unescaped_backticks.rs | ||
| unescaped_backticks.stderr | ||
| unused-extern-crate.rs | ||
| use_both_out_dir_and_output_options.rs | ||
| use_both_out_dir_and_output_options.stderr | ||
| wasm-safe.rs | ||