Skip to content

Commit

Permalink
Stabilize custom_code_classes_in_docs feature
Browse files Browse the repository at this point in the history
  • Loading branch information
GuillaumeGomez committed May 1, 2024
1 parent 378a43a commit 2f6abd1
Show file tree
Hide file tree
Showing 23 changed files with 67 additions and 515 deletions.
2 changes: 2 additions & 0 deletions compiler/rustc_feature/src/accepted.rs
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,8 @@ declare_features! (
(accepted, copy_closures, "1.26.0", Some(44490)),
/// Allows `crate` in paths.
(accepted, crate_in_paths, "1.30.0", Some(45477)),
/// Allows users to provide classes for fenced code block using `class:classname`.
(accepted, custom_code_classes_in_docs, "CURRENT_RUSTC_VERSION", Some(79483)),
/// Allows using `#[debugger_visualizer]` attribute.
(accepted, debugger_visualizer, "1.71.0", Some(95939)),
/// Allows rustc to inject a default alloc_error_handler
Expand Down
2 changes: 0 additions & 2 deletions compiler/rustc_feature/src/unstable.rs
Original file line number Diff line number Diff line change
Expand Up @@ -424,8 +424,6 @@ declare_features! (
/// Allows function attribute `#[coverage(on/off)]`, to control coverage
/// instrumentation of that function.
(unstable, coverage_attribute, "1.74.0", Some(84605)),
/// Allows users to provide classes for fenced code block using `class:classname`.
(unstable, custom_code_classes_in_docs, "1.74.0", Some(79483)),
/// Allows non-builtin attributes in inner attribute position.
(unstable, custom_inner_attributes, "1.30.0", Some(54726)),
/// Allows custom test frameworks with `#![test_runner]` and `#[test_case]`.
Expand Down
44 changes: 0 additions & 44 deletions src/doc/rustdoc/src/unstable-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -624,47 +624,3 @@ add the `--scrape-tests` flag.

This flag enables the generation of links in the source code pages which allow the reader
to jump to a type definition.

### Custom CSS classes for code blocks

```rust
#![feature(custom_code_classes_in_docs)]

/// ```custom,{class=language-c}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```

The text `int main(void) { return 0; }` is rendered without highlighting in a code block
with the class `language-c`. This can be used to highlight other languages through JavaScript
libraries for example.

Without the `custom` attribute, it would be generated as a Rust code example with an additional
`language-C` CSS class. Therefore, if you specifically don't want it to be a Rust code example,
don't forget to add the `custom` attribute.

To be noted that you can replace `class=` with `.` to achieve the same result:

```rust
#![feature(custom_code_classes_in_docs)]

/// ```custom,{.language-c}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```

To be noted, `rust` and `.rust`/`class=rust` have different effects: `rust` indicates that this is
a Rust code block whereas the two others add a "rust" CSS class on the code block.

You can also use double quotes:

```rust
#![feature(custom_code_classes_in_docs)]

/// ```"not rust" {."hello everyone"}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```
38 changes: 38 additions & 0 deletions src/doc/rustdoc/src/write-documentation/documentation-tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -376,6 +376,44 @@ that the code sample should be compiled using the respective edition of Rust.
# fn foo() {}
```

### Custom CSS classes for code blocks

```rust
/// ```custom,{class=language-c}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```

The text `int main(void) { return 0; }` is rendered without highlighting in a code block
with the class `language-c`. This can be used to highlight other languages through JavaScript
libraries for example.

Without the `custom` attribute, it would be generated as a Rust code example with an additional
`language-C` CSS class. Therefore, if you specifically don't want it to be a Rust code example,
don't forget to add the `custom` attribute.

To be noted that you can replace `class=` with `.` to achieve the same result:

```rust
/// ```custom,{.language-c}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```

To be noted, `rust` and `.rust`/`class=rust` have different effects: `rust` indicates that this is
a Rust code block whereas the two others add a "rust" CSS class on the code block.

You can also use double quotes:

```rust
/// ```"not rust" {."hello everyone"}
/// int main(void) { return 0; }
/// ```
pub struct Bar;
```

## Syntax reference

The *exact* syntax for code blocks, including the edge cases, can be found
Expand Down
1 change: 0 additions & 1 deletion src/librustdoc/doctest.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1345,7 +1345,6 @@ impl<'a, 'hir, 'tcx> HirCollector<'a, 'hir, 'tcx> {
def_id.to_def_id(),
span_of_fragments(&attrs.doc_strings).unwrap_or(sp),
)),
self.tcx.features().custom_code_classes_in_docs,
);
}

Expand Down
4 changes: 0 additions & 4 deletions src/librustdoc/externalfiles.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,6 @@ impl ExternalHtml {
edition,
playground,
heading_offset: HeadingOffset::H2,
// For external files, it'll be disabled until the feature is enabled by default.
custom_code_classes_in_docs: false,
}
.into_string()
);
Expand All @@ -63,8 +61,6 @@ impl ExternalHtml {
edition,
playground,
heading_offset: HeadingOffset::H2,
// For external files, it'll be disabled until the feature is enabled by default.
custom_code_classes_in_docs: false,
}
.into_string()
);
Expand Down
Loading

0 comments on commit 2f6abd1

Please sign in to comment.