[rustdoc] Wrap code blocks in <code> tag#88093

Kobzol · 2021-08-16T21:24:01Z

This PR modifies Rustdoc output so that fenced code snippets, items and whole file source codes are wrapped in <pre><code> instead of just <pre>. This should improve the semantic meaning of the generated content.

I'm not sure what to do about render_attributes_in_pre and render_attributes_in_code. These functions were clearly expected to be used for things inside <pre> or <code>, and since I added <code> in this PR, some of them will be used in a different context than before. However, it seems to me that even before they were not consistent. For example, item_constant used render_attributes_in_code for its attributes, however there was no <code> used for constants before this PR...

Should I create some rustdoc-gui tests? For example to check that all <pre> tags have a <code> child?

Fixes: #88020

rust-highfive · 2021-08-16T21:24:04Z

r? @ollie27

(rust-highfive has picked a reviewer for you, use r? to override)

src/librustdoc/html/highlight.rs

src/librustdoc/html/render/print_item.rs

src/test/rustdoc-gui/type-declation-overflow.goml

GuillaumeGomez · 2021-08-18T18:28:24Z

I'm not sure what to do about render_attributes_in_pre and render_attributes_in_code. These functions were clearly expected to be used for things inside <pre> or <code>, and since I added <code> in this PR, some of them will be used in a different context than before. However, it seems to me that even before they were not consistent. For example, item_constant used render_attributes_in_code for its attributes, however there was no <code> used for constants before this PR...

Another shortcoming of rustdoc... Welcome to a huge years old codebase! :)

For consistency it should be applied the same on equivalent items but I think it's a bit out of scope here. For things other than codeblocks, just having a <code> (without the <pre> wrapping) is fine.

Should I create some rustdoc-gui tests? For example to check that all <pre> tags have a <code> child?

Well, not all <code> are supposed to be wrapped. For example, an inline code in documentation like this one isn't supposed to be wrapped into a <pre>.

But enforcing the existing is always a good idea and such a test would be very welcome. :)

jyn514 · 2021-08-19T00:24:30Z

r? @GuillaumeGomez

Kobzol · 2021-08-19T07:49:09Z

I changed the newlines after <pre><code>, now no newline is generated. I also added a simple test that checks that a few item types and doc code blocks contain <pre><code>.

src/librustdoc/html/render/print_item.rs

GuillaumeGomez · 2021-08-19T15:55:07Z

I checked locally and it looks good to me.

Thanks!

@bors: r+

bors · 2021-08-19T15:55:09Z

📌 Commit ccd550e has been approved by GuillaumeGomez

…laumeGomez Rollup of 8 pull requests Successful merges: - rust-lang#86123 (Preserve more spans in internal `rustc_queries!` macro) - rust-lang#87874 (Add TcpStream type to TcpListener::incoming docs) - rust-lang#88034 (rustc_privacy: Replace `HirId`s and `DefId`s with `LocalDefId`s where possible) - rust-lang#88050 (Remove `HashStable` impls for `FileName` and `RealFileName`) - rust-lang#88093 ([rustdoc] Wrap code blocks in `<code>` tag) - rust-lang#88146 (Add tests for some `feature(const_evaluatable_checked)` incr comp issues) - rust-lang#88153 (Update .mailmap) - rust-lang#88159 (Use a trait instead of the now disallowed missing trait there) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rust-highfive assigned ollie27 Aug 16, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 16, 2021

GuillaumeGomez added A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Aug 18, 2021

GuillaumeGomez reviewed Aug 18, 2021

View reviewed changes

src/librustdoc/html/highlight.rs Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Aug 18, 2021

View reviewed changes

src/librustdoc/html/render/print_item.rs Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Aug 18, 2021

View reviewed changes

src/test/rustdoc-gui/type-declation-overflow.goml Outdated Show resolved Hide resolved

rust-highfive assigned GuillaumeGomez and unassigned ollie27 Aug 19, 2021

Kobzol force-pushed the rustdoc-wrap-code-in-code-tag branch from 0c3f394 to 378d92c Compare August 19, 2021 07:48

GuillaumeGomez reviewed Aug 19, 2021

View reviewed changes

src/librustdoc/html/render/print_item.rs Outdated Show resolved Hide resolved

[rustdoc] Wrap code blocks in <code> tag

ccd550e

Kobzol force-pushed the rustdoc-wrap-code-in-code-tag branch from 378d92c to ccd550e Compare August 19, 2021 08:30

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 19, 2021

GuillaumeGomez mentioned this pull request Aug 19, 2021

Rollup of 8 pull requests #88165

Merged

bors merged commit 10165f8 into rust-lang:master Aug 19, 2021

rustbot added this to the 1.56.0 milestone Aug 19, 2021

Kobzol deleted the rustdoc-wrap-code-in-code-tag branch August 20, 2021 06:11

camelid mentioned this pull request Aug 28, 2021

rustdoc: Ayu syntax highlighting regression #88415

Closed

gemmaro mentioned this pull request Nov 14, 2021

[ mkdoc ] Wrap declaration part in <code> tag idris-lang/Idris2#2121

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[rustdoc] Wrap code blocks in <code> tag#88093