Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Weird formatting on documentation of "Summary" button #132564

Closed
lolbinarycat opened this issue Nov 3, 2024 · 4 comments · Fixed by #132617
Closed

Weird formatting on documentation of "Summary" button #132564

lolbinarycat opened this issue Nov 3, 2024 · 4 comments · Fixed by #132617
Assignees
@uellenberg
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.

Comments

@lolbinarycat
Copy link
Contributor

lolbinarycat commented Nov 3, 2024 •
edited by rustbot
Loading

location: https://doc.rust-lang.org/nightly/std/#how-to-read-this-documentation

I believe this issue comes from using an svg element inside a code element.

Image
@lolbinarycat lolbinarycat added A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Nov 3, 2024
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Nov 3, 2024
@jieyouxu jieyouxu added A-rustdoc-ui Area: Rustdoc UI (generated HTML) and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Nov 4, 2024
@uellenberg
Copy link
Contributor

This is due to "Summary" having a newline in it. You can see the newline in

rust/library/std/src/lib.rs

Lines 35 to 36 in 82c24ec

//! development you may want to press the <code>
//! <svg style="width:0.75rem;height:0.75rem" viewBox="0 0 12 12"
, where code is on a different line than the SVG.

I'm going to send in a modification, but I'm not sure how to document why that change is being made, so it doesn't happen again. A quick search through the code confirms that this is the only place where we have an inside a in a Rust source file.

@rustbot claim

uellenberg added a commit to uellenberg/rust that referenced this issue Nov 4, 2024
@uellenberg
Fix an extra newline in rendered std doc
0d158aa 
Fixes rust-lang#132564
@lolbinarycat
Copy link
Contributor Author

I'm not sure how to document why that change is being made, so it doesn't happen again.

you can put a non-doc comment (//) next to the doc comment.

@uellenberg
Copy link
Contributor

uellenberg commented Nov 4, 2024 •
edited
Loading

I'm not sure how to document why that change is being made, so it doesn't happen again.

you can put a non-doc comment (//) next to the doc comment.

Good idea!

On second thought, I don't love the idea of breaking up documentation with notes on why the documentation is formatted the way it is. I think this isn't so big of an issue that it needs to be commented on.

@uellenberg uellenberg mentioned this issue Nov 4, 2024
Merged
@lolbinarycat
Copy link
Contributor Author

another option is coding a check into tidy that prevents putting newlines inside inline html elements (as opposed to block html elements, which can have newlines without much issue)

uellenberg added a commit to uellenberg/rust that referenced this issue Nov 5, 2024
@uellenberg
Fix an extra newline in rendered std doc
de53321 
Fixes rust-lang#132564
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Nov 6, 2024
@GuillaumeGomez
Rollup merge of rust-lang#132617 - uellenberg:fix-rendered-doc, r=cuv…
d6a43d4 
…iper

Fix an extra newline in rendered std doc

Fixes rust-lang#132564

![17308581942254367500907812250579](https://github.com/user-attachments/assets/9e946c49-c0a6-40ba-ab69-b80fe0e085e1)
(taken from the issue above)

The problem with the formatting is due to that newline between `<code>` and `<svg>`. Any newlines outside of the code (i.e., within elements inside of it) are fine.
@bors bors closed this as completed in 934be9b Nov 6, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Nov 6, 2024
@rust-timer
Unrolled build for rust-lang#132617
f1918d1 
Rollup merge of rust-lang#132617 - uellenberg:fix-rendered-doc, r=cuviper

Fix an extra newline in rendered std doc

Fixes rust-lang#132564

![17308581942254367500907812250579](https://github.com/user-attachments/assets/9e946c49-c0a6-40ba-ab69-b80fe0e085e1)
(taken from the issue above)

The problem with the formatting is due to that newline between `<code>` and `<svg>`. Any newlines outside of the code (i.e., within elements inside of it) are fine.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@uellenberg uellenberg

Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-rustdoc-ui Area: Rustdoc UI (generated HTML) T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Fix an extra newline in rendered std doc uellenberg/rust
4 participants
@lolbinarycat @jieyouxu @rustbot @uellenberg