rust
rust copied to clipboard
rust-lang
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 thecustomattribute. - 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:
<pre class="language-c">
int main(void) {
return 0;
}</pre>
Instead of:
<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:
/// ```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.
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
The job mingw-check-tidy failed! Check out the build log: (web) (plain)
Click to see the possible cause of the failure (guessed by this bot)
Getting action download info
Download action repository 'msys2/[email protected]' (SHA:cc11e9188b693c2b100158c3322424c4cc1dadea)
Download action repository 'actions/checkout@v4' (SHA:0ad4b8fadaa221de15dcec353f45205ec38ea70b)
Download action repository 'actions/upload-artifact@v4' (SHA:65462800fd760344b1a7b4382951275a0abb4808)
Complete job name: PR - mingw-check-tidy
git config --global core.autocrlf false
shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
---
COPY scripts/sccache.sh /scripts/
RUN sh /scripts/sccache.sh
COPY host-x86_64/mingw-check/reuse-requirements.txt /tmp/
RUN pip3 install --no-deps --no-cache-dir --require-hashes -r /tmp/reuse-requirements.txt \
&& pip3 install virtualenv
COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/
# NOTE: intentionally uses python2 for x.py so we can test it still works.
# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
--stage 0 src/tools/tidy tidyselftest --extra-checks=py:lint
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
# pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#12 [5/8] COPY host-x86_64/mingw-check/reuse-requirements.txt /tmp/
#12 DONE 0.0s
#13 [6/8] RUN pip3 install --no-deps --no-cache-dir --require-hashes -r /tmp/reuse-requirements.txt && pip3 install virtualenv
#13 0.448 Downloading binaryornot-0.4.4-py2.py3-none-any.whl (9.0 kB)
#13 0.464 Collecting boolean-py==4.0
#13 0.472 Downloading boolean.py-4.0-py3-none-any.whl (25 kB)
#13 0.490 Collecting chardet==5.1.0
---
#13 3.667 Building wheels for collected packages: reuse
#13 3.668 Building wheel for reuse (pyproject.toml): started
#13 4.002 Building wheel for reuse (pyproject.toml): finished with status 'done'
#13 4.003 Created wheel for reuse: filename=reuse-1.1.0-cp310-cp310-manylinux_2_35_x86_64.whl size=181117 sha256=f5f58750481f69515c2c0d1d503daf565e2565c370d07fc6aeb95fe3498b4269
#13 4.003 Stored in directory: /tmp/pip-ephem-wheel-cache-_lybe83z/wheels/c2/3c/b9/1120c2ab4bd82694f7e6f0537dc5b9a085c13e2c69a8d0c76d
#13 4.005 Installing collected packages: boolean-py, binaryornot, setuptools, reuse, python-debian, markupsafe, license-expression, jinja2, chardet
#13 4.027 Attempting uninstall: setuptools
#13 4.028 Found existing installation: setuptools 59.6.0
#13 4.029 Not uninstalling setuptools at /usr/lib/python3/dist-packages, outside environment /usr
#13 4.029 Not uninstalling setuptools at /usr/lib/python3/dist-packages, outside environment /usr
#13 4.029 Can't uninstall 'setuptools'. No files were found to uninstall.
#13 4.712 Successfully installed binaryornot-0.4.4 boolean-py-4.0 chardet-5.1.0 jinja2-3.1.2 license-expression-30.0.0 markupsafe-2.1.1 python-debian-0.1.49 reuse-1.1.0 setuptools-66.0.0
#13 4.713 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#13 5.245 Collecting virtualenv
#13 5.301 Downloading virtualenv-20.26.1-py3-none-any.whl (3.9 MB)
#13 5.486 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.9/3.9 MB 21.5 MB/s eta 0:00:00
#13 5.526 Collecting distlib<1,>=0.3.7
#13 5.534 Downloading distlib-0.3.8-py2.py3-none-any.whl (468 kB)
#13 5.546 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 468.9/468.9 KB 45.9 MB/s eta 0:00:00
#13 5.579 Collecting platformdirs<5,>=3.9.1
#13 5.586 Downloading platformdirs-4.2.1-py3-none-any.whl (17 kB)
#13 5.622 Collecting filelock<4,>=3.12.2
#13 5.629 Downloading filelock-3.14.0-py3-none-any.whl (12 kB)
#13 5.720 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#13 5.884 Successfully installed distlib-0.3.8 filelock-3.14.0 platformdirs-4.2.1 virtualenv-20.26.1
#13 DONE 6.0s
#14 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#14 DONE 0.0s
---
DirectMap4k: 198592 kB
DirectMap2M: 7141376 kB
DirectMap1G: 11534336 kB
##[endgroup]
Executing TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py:lint
+ TIDY_PRINT_DIFF=1 python2.7 ../x.py test --stage 0 src/tools/tidy tidyselftest --extra-checks=py:lint
Finished `dev` profile [unoptimized] target(s) in 0.03s
##[endgroup]
downloading https://ci-artifacts.rust-lang.org/rustc-builds-alt/378a43a06510f3e3a49c69c8de71745e6a884048/rust-dev-nightly-x86_64-unknown-linux-gnu.tar.xz
extracting /checkout/obj/build/cache/llvm-378a43a06510f3e3a49c69c8de71745e6a884048-true/rust-dev-nightly-x86_64-unknown-linux-gnu.tar.xz to /checkout/obj/build/x86_64-unknown-linux-gnu/ci-llvm
---
Compiling tidy v0.1.0 (/checkout/src/tools/tidy)
Finished `release` profile [optimized] target(s) in 24.83s
##[endgroup]
fmt check
##[error]Diff in /checkout/src/librustdoc/passes/calculate_doc_coverage.rs at line 208:
let has_docs = !i.attrs.doc_strings.is_empty();
let mut tests = Tests { found_tests: 0 };
- find_testable_code(
- find_testable_code(
- &i.doc_value(),
- ErrorCodes::No,
- false,
- None,
- );
- );
+ find_testable_code(&i.doc_value(), &mut tests, ErrorCodes::No, false, None);
let has_doc_example = tests.found_tests != 0;
let hir_id = DocContext::as_local_hir_id(self.ctx.tcx, i.item_id).unwrap();
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 213:
edition: Edition,
playground: &'p Option<Playground>,
- CodeBlocks {
- inner: iter,
- check_error_codes: error_codes,
- edition,
- edition,
- playground,
- }
+ CodeBlocks { inner: iter, check_error_codes: error_codes, edition, playground }
}
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 245:
let LangString { added_classes, compile_fail, should_panic, ignore, edition, .. } =
match kind {
CodeBlockKind::Fenced(ref lang) => {
- lang,
- self.check_error_codes,
- false,
- );
- );
+ let parse_result =
+ LangString::parse_without_check(lang, self.check_error_codes, false);
if !parse_result.rust {
let added_classes = parse_result.added_classes;
let lang_string = if let Some(lang) = parse_result.unknown.first() {
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 725:
enable_per_target_ignores: bool,
extra_info: Option<&ExtraInfo<'_>>,
- find_codes(
- doc,
- tests,
- error_codes,
- error_codes,
- enable_per_target_ignores,
- extra_info,
- false,
- )
+ find_codes(doc, tests, error_codes, enable_per_target_ignores, extra_info, false)
pub(crate) fn find_codes<T: doctest::Tester>(
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 1178:
allow_error_code_check: ErrorCodes,
) -> Self {
- Self::parse(
- string,
- allow_error_code_check,
- allow_error_code_check,
- enable_per_target_ignores,
- None,
- )
+ Self::parse(string, allow_error_code_check, enable_per_target_ignores, None)
}
fn parse(
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 1387:
impl MarkdownWithToc<'_> {
pub(crate) fn into_string(self) -> String {
- let MarkdownWithToc {
- content: md,
- ids,
- error_codes: codes,
- playground,
- } = self;
- } = self;
+ let MarkdownWithToc { content: md, ids, error_codes: codes, edition, playground } = self;
let p = Parser::new_ext(md, main_body_opts()).into_offset_iter();
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 1846:
/// Returns a range of bytes for each code block in the markdown that is tagged as `rust` or
/// Returns a range of bytes for each code block in the markdown that is tagged as `rust` or
/// untagged (and assumed to be rust).
-pub(crate) fn rust_code_blocks(
- md: &str,
- extra_info: &ExtraInfo<'_>,
-) -> Vec<RustCodeBlock> {
+pub(crate) fn rust_code_blocks(md: &str, extra_info: &ExtraInfo<'_>) -> Vec<RustCodeBlock> {
let mut code_blocks = vec![];
if md.is_empty() {
##[error]Diff in /checkout/src/librustdoc/html/markdown.rs at line 1866:
let lang_string = if syntax.is_empty() {
} else {
- LangString::parse(
- &*syntax,
- ErrorCodes::Yes,
- ErrorCodes::Yes,
- false,
- Some(extra_info),
- )
+ LangString::parse(&*syntax, ErrorCodes::Yes, false, Some(extra_info))
};
if !lang_string.rust {
continue;
##[error]Diff in /checkout/src/librustdoc/passes/check_doc_test_visibility.rs at line 112:
let mut tests = Tests { found_tests: 0 };
- find_testable_code(
- dox,
- dox,
- &mut tests,
- ErrorCodes::No,
- false,
- None,
- );
+ find_testable_code(dox, &mut tests, ErrorCodes::No, false, None);
if tests.found_tests == 0 && cx.tcx.features().rustdoc_missing_doc_code_examples {
if should_have_doc_example(cx, item) {
Running `"/checkout/obj/build/x86_64-unknown-linux-gnu/rustfmt/bin/rustfmt" "--config-path" "/checkout" "--edition" "2021" "--unstable-features" "--skip-children" "--check" "/checkout/library/core/tests/iter/adapters/filter_map.rs" "/checkout/library/core/tests/iter/adapters/map_windows.rs" "/checkout/library/core/tests/iter/adapters/cycle.rs" "/checkout/library/core/tests/iter/adapters/map.rs" "/checkout/library/core/tests/iter/adapters/by_ref_sized.rs" "/checkout/library/core/tests/iter/adapters/inspect.rs" "/checkout/library/core/tests/iter/adapters/scan.rs" "/checkout/library/core/tests/iter/adapters/step_by.rs" "/checkout/library/core/tests/iter/adapters/copied.rs" "/checkout/library/core/tests/iter/adapters/take_while.rs" "/checkout/library/core/tests/iter/adapters/peekable.rs" "/checkout/library/core/tests/iter/adapters/mod.rs" "/checkout/library/core/tests/iter/adapters/cloned.rs" "/checkout/library/core/tests/iter/adapters/chain.rs" "/checkout/library/core/tests/iter/adapters/fuse.rs" "/checkout/library/core/tests/iter/adapters/take.rs" "/checkout/library/core/tests/iter/adapters/flatten.rs" "/checkout/library/core/tests/iter/adapters/intersperse.rs" "/checkout/library/core/tests/iter/adapters/flat_map.rs" "/checkout/library/core/tests/iter/adapters/skip_while.rs" "/checkout/library/core/tests/iter/sources.rs" "/checkout/library/core/tests/iter/mod.rs" "/checkout/library/core/tests/iter/range.rs" "/checkout/library/core/tests/lib.rs" "/checkout/library/core/tests/task.rs" "/checkout/library/core/tests/asserting.rs" "/checkout/library/core/tests/any.rs" "/checkout/library/core/tests/future.rs" "/checkout/src/librustdoc/html/markdown.rs" "/checkout/src/librustdoc/html/length_limit/tests.rs" "/checkout/src/librustdoc/html/mod.rs" "/checkout/src/librustdoc/html/markdown/tests.rs" "/checkout/src/librustdoc/html/toc/tests.rs" "/checkout/src/librustdoc/html/escape.rs" "/checkout/src/librustdoc/html/render/search_index/encode.rs" "/checkout/src/librustdoc/html/render/search_index.rs" "/checkout/src/librustdoc/html/render/print_item.rs" "/checkout/src/librustdoc/html/render/mod.rs" "/checkout/src/librustdoc/html/render/type_layout.rs" "/checkout/src/librustdoc/html/render/sidebar.rs" "/checkout/src/librustdoc/html/render/write_shared.rs" "/checkout/src/librustdoc/html/render/span_map.rs" "/checkout/src/librustdoc/html/render/context.rs" "/checkout/src/librustdoc/html/render/tests.rs" "/checkout/src/librustdoc/html/format.rs" "/checkout/src/librustdoc/html/highlight/fixtures/union.rs" "/checkout/src/librustdoc/html/highlight/fixtures/sample.rs" "/checkout/src/librustdoc/html/highlight/tests.rs" "/checkout/src/librustdoc/html/tests.rs" "/checkout/src/librustdoc/html/url_parts_builder/tests.rs" "/checkout/src/librustdoc/html/toc.rs" "/checkout/src/etc/test-float-parse/src/lib.rs" "/checkout/src/etc/test-float-parse/src/bin/many-digits.rs" "/checkout/src/etc/test-float-parse/src/bin/u64-pow2.rs" "/checkout/src/etc/test-float-parse/src/bin/few-ones.rs" "/checkout/src/etc/test-float-parse/src/bin/huge-pow10.rs" "/checkout/src/etc/test-float-parse/src/bin/rand-f64.rs" "/checkout/src/etc/test-float-parse/src/bin/subnorm.rs" "/checkout/src/etc/test-float-parse/src/bin/long-fractions.rs" "/checkout/src/etc/test-float-parse/src/bin/short-decimals.rs" "/checkout/src/etc/test-float-parse/src/bin/tiny-pow10.rs" "/checkout/src/etc/test-float-parse/src/bin/u32-small.rs" "/checkout/library/core/tests/io/mod.rs" "/checkout/library/core/tests/iter/adapters/skip.rs"` failed.
If you're running `tidy`, try again with `--bless`. Or, if you just want to format code, run `./x.py fmt` instead.
local time: Wed May 1 13:31:02 UTC 2024
network time: Diff in /checkout/src/librustdoc/markdown.rs at line 164:
network time: Diff in /checkout/src/librustdoc/markdown.rs at line 164:
let codes = ErrorCodes::from(options.unstable_features.is_nightly_build());
// For markdown files, custom code classes will be disabled until the feature is enabled by default.
- find_testable_code(
- &input_str,
- &mut collector,
- &mut collector,
- codes,
- options.enable_per_target_ignores,
- None,
- );
+ find_testable_code(&input_str, &mut collector, codes, options.enable_per_target_ignores, None);
crate::doctest::run_tests(options.test_args, options.nocapture, collector.tests);
Wed, 01 May 2024 13:31:02 GMT
##[error]Process completed with exit code 1.
Post job cleanup.
The job x86_64-gnu-llvm-17 failed! Check out the build log: (web) (plain)
Click to see the possible cause of the failure (guessed by this bot)
#16 exporting to docker image format
#16 sending tarball 29.6s done
#16 DONE 35.5s
##[endgroup]
Setting extra environment values for docker: --env ENABLE_GCC_CODEGEN=1 --env GCC_EXEC_PREFIX=/usr/lib/gcc/
[CI_JOB_NAME=x86_64-gnu-llvm-17]
---
sccache: Starting the server...
##[group]Configure the build
configure: processing command line
configure:
configure: build.configure-args := ['--build=x86_64-unknown-linux-gnu', '--llvm-root=/usr/lib/llvm-17', '--enable-llvm-link-shared', '--set', 'rust.thin-lto-import-instr-limit=10', '--set', 'change-id=99999999', '--enable-verbose-configure', '--enable-sccache', '--disable-manage-submodules', '--enable-locked-deps', '--enable-cargo-native-static', '--set', 'rust.codegen-units-std=1', '--set', 'dist.compression-profile=balanced', '--dist-compression-formats=xz', '--disable-dist-src', '--release-channel=nightly', '--enable-debug-assertions', '--enable-overflow-checks', '--enable-llvm-assertions', '--set', 'rust.verify-llvm-ir', '--set', 'rust.codegen-backends=llvm,cranelift,gcc', '--set', 'llvm.static-libstdcpp', '--enable-new-symbol-mangling']
configure: target.x86_64-unknown-linux-gnu.llvm-config := /usr/lib/llvm-17/bin/llvm-config
configure: llvm.link-shared := True
configure: rust.thin-lto-import-instr-limit := 10
configure: change-id := 99999999
---
Downloaded boml v0.3.1
Compiling boml v0.3.1
Compiling y v0.1.0 (/checkout/compiler/rustc_codegen_gcc/build_system)
Finished `release` profile [optimized] target(s) in 3.39s
Running `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-codegen/x86_64-unknown-linux-gnu/release/y test --use-system-gcc --use-backend gcc --out-dir /checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools/cg_gcc --release --mini-tests --std-tests`
Using system GCC
[BUILD] example
[AOT] mini_core_hello_world
/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools/cg_gcc/mini_core_hello_world
abc
---
Compiling rustdoc v0.0.0 (/checkout/src/librustdoc)
error[E0061]: this function takes 4 arguments but 5 arguments were supplied
--> src/librustdoc/html/markdown/tests.rs:52:20
|
52 | assert_eq!(LangString::parse(s, ErrorCodes::Yes, true, None, true), lg)
| | |
| | unexpected argument of type `bool`
| help: remove the extra argument
|
---
1171 | allow_error_code_check: ErrorCodes,
| ----------------------------------
1172 | enable_per_target_ignores: bool,
| -------------------------------
1173 | extra: Option<&ExtraInfo<'_>>,
error[E0061]: this function takes 5 arguments but 6 arguments were supplied
--> src/librustdoc/html/markdown/tests.rs:482:9
|
---
|
note: function defined here
--> src/librustdoc/html/markdown.rs:713:15
|
713 | pub(crate) fn find_testable_code<T: doctest::Tester>(
714 | doc: &str,
| ---------
715 | tests: &mut T,
| -------------
| -------------
716 | error_codes: ErrorCodes,
| -----------------------
717 | enable_per_target_ignores: bool,
| -------------------------------
718 | extra_info: Option<&ExtraInfo<'_>>,
For more information about this error, try `rustc --explain E0061`.
error: could not compile `rustdoc` (lib test) due to 2 previous errors
warning: build failed, waiting for other jobs to finish...
Team member @notriddle has proposed to merge this. The next step is review by the rest of the tagged team members:
- [ ] @Aaron1011
- [x] @GuillaumeGomez
- [ ] @Manishearth
- [ ] @Nemo157
- [ ] @aDotInTheVoid
- [ ] @camelid
- [ ] @cjgillot
- [ ] @compiler-errors
- [ ] @davidtwco
- [ ] @eddyb
- [ ] @estebank
- [ ] @jackh726
- [ ] @jsha
- [ ] @lcnr
- [ ] @matthewjasper
- [ ] @michaelwoerister
- [ ] @nagisa
- [x] @notriddle
- [ ] @oli-obk
- [ ] @petrochenkov
- [ ] @pnkfelix
- [ ] @wesleywiser
No concerns currently listed.
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!
See this document for info about what commands tagged team members can give me.
Hum, why is the compiler team part of this? Because of the feature in the compiler source maybe?
@rfcbot fcp cancel
Autotagged. I don't think the compiler team needs to participate in this.
Oh it's based on PR's tags and not the source code. Noted. Thanks compiler-errors!
@rfcbot fcp merge
Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:
- [x] @GuillaumeGomez
- [x] @Manishearth
- [x] @Nemo157
- [ ] @aDotInTheVoid
- [x] @camelid
- [ ] @jsha
- [x] @notriddle
Concerns:
- ~~syntax complexity~~ resolved by https://github.com/rust-lang/rust/pull/124577#issuecomment-2123894727
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!
See this document for info about what commands tagged team members can give me.
Do you mind posting a brief summary of the feature as it currently stands? It seems there was a lot of back-and-forth over things like syntax in the implementation PR.
Good point! Having a summary will be a nice addition. Should have thought about it... (The first comment of the original PR was up-to-date but it's better to have it here as well)
@rfcbot concern syntax complexity
This seems good overall, but a couple comments:
- Is there any particular reason for supporting both
{class=foo}and{.foo}? It seems like Pandoc only supports the second variant, so unless there's a strong reason to support both, it might be better to keep it simple. - Do you mind elaborating on the purpose of tracking "unknown tags"? In the case of
custom,class:language-c, that seems like a syntax error that should be reported as such, since the only supported syntax is{.foo}(and{class=foo}if we decide to keep that).
Is there any particular reason for supporting both
{class=foo}and{.foo}? It seems like Pandoc only supports the second variant, so unless there's a strong reason to support both, it might be better to keep it simple.
Pandoc supports both variants.
Do you mind elaborating on the purpose of tracking "unknown tags"?
https://github.com/rust-lang/rust/issues/115938 / https://github.com/rust-lang/rust/pull/115947#issuecomment-1724361386
Thanks, I didn't see that in the docs. 👍
https://github.com/rust-lang/rust/issues/115938 / https://github.com/rust-lang/rust/pull/115947#issuecomment-1724361386
Hmm, I'm still unclear on how this relates to the custom,class:language-c example given above. I agree that we should support ASN.1, but based on the PR's description, it seems to also add support for class:foo as syntax that adds a class, in addition to {class=foo} and {.foo}. Am I misunderstanding?
It doesn't add class:foo as syntax that adds a class. It's just a bareword, the same as ASN.1. The colon isn't special syntax at all. The PR description with that example is outdated.
A current description of this feature can be found in the rustdoc book:
https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#custom-css-classes-for-code-blocks
while the corner cases are mostly found in test cases:
https://github.com/rust-lang/rust/blob/54cdc13542ef548e7d7f71cd48cc9e4f239e0e25/src/librustdoc/html/markdown/tests.rs#L49
It doesn't add
class:fooas syntax that adds a class. It's just a bareword, the same asASN.1. The colon isn't special syntax at all. The PR description with that example is outdated.
Ah, I see. I tested it locally and see what you mean. I'll update the PR's description.
@rfcbot resolve syntax complexity
The final comment period, with a disposition to merge, as per the review above, is now complete.
As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.
This will be merged soon.
:pushpin: Commit 2f6abd190da3dba44058253cbbfdb900906ef1b6 has been approved by rustdoc
It is now in the queue for this repository.
:hourglass: Testing commit 2f6abd190da3dba44058253cbbfdb900906ef1b6 with merge 05965ae238403d8c141170b411245a62aa046240...
:sunny: Test successful - checks-actions Approved by: rustdoc Pushing 05965ae238403d8c141170b411245a62aa046240 to master...
Finished benchmarking commit (05965ae238403d8c141170b411245a62aa046240): comparison URL.
Overall result: ✅ improvements - no action needed
@rustbot label: -perf-regression
Instruction count
This is a highly reliable metric that was used to determine the overall result at the top of this comment.
| mean | range | count | |
|---|---|---|---|
| Regressions ❌ (primary) |
- | - | 0 |
| Regressions ❌ (secondary) |
- | - | 0 |
| Improvements ✅ (primary) |
-0.4% | [-0.8%, -0.2%] | 9 |
| Improvements ✅ (secondary) |
-0.7% | [-0.9%, -0.5%] | 2 |
| All ❌✅ (primary) | -0.4% | [-0.8%, -0.2%] | 9 |
Max RSS (memory usage)
Results (primary 1.4%)
This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
| mean | range | count | |
|---|---|---|---|
| Regressions ❌ (primary) |
1.4% | [1.4%, 1.4%] | 1 |
| Regressions ❌ (secondary) |
- | - | 0 |
| Improvements ✅ (primary) |
- | - | 0 |
| Improvements ✅ (secondary) |
- | - | 0 |
| All ❌✅ (primary) | 1.4% | [1.4%, 1.4%] | 1 |
Cycles
Results (secondary 2.9%)
This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.
| mean | range | count | |
|---|---|---|---|
| Regressions ❌ (primary) |
- | - | 0 |
| Regressions ❌ (secondary) |
2.9% | [2.1%, 4.4%] | 10 |
| Improvements ✅ (primary) |
- | - | 0 |
| Improvements ✅ (secondary) |
- | - | 0 |
| All ❌✅ (primary) | - | - | 0 |
Binary size
This benchmark run did not return any relevant results for this metric.
Bootstrap: 668.037s -> 668.888s (0.13%) Artifact size: 318.86 MiB -> 318.81 MiB (-0.02%)
This PR seems to have caused a regression (or at least a possibly unexpected behaviour change) that affects a large-ish number of crates - previously, code block attributes that were not recognized as "rust code" in some way were ignored and not compiled, but now "invalid" code block attributes raise a new rustdoc warning lint, but are compiled (and run) as Rust code.
For example, the code blocks here use {rust,ignore} instead of rust,ignore - they were previously ignored, but are now attempted to be compiled + run:
https://github.com/servo/rust-cssparser/blob/main/src/lib.rs#L44-L64
I noticed this because the CI we have for Fedora packages started to turn red for 2-3 dozen Rust crates after Rust 1.80 landed a few days ago.
Was this behaviour change intentional? While I agree that it is likely a good idea to warn on "invalid" or unrecognized code block attributes, attempting to compile + run code blocks with unrecognized attributes might not be.
