Skip to content

rustdoc styling issue: .docblock occasionally has problematic right padding #86184

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.

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

Closed
davidbarsky opened this issue Jun 9, 2021 · 5 comments
Closed
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@davidbarsky
Copy link
Contributor

In tracing, we use warnings blocks to surface potential gotchas to users (this is arguably a misuse of blocks in rustdoc, but anyways...). Unforuntately, I noticed that blocks add 1ex of right padding to anything rendered as code, including inline comments. Here's an example: https://deploy-preview-1430--tracing-rs.netlify.app/tracing/struct.span#method.entered. A screenshot is below for posterity.

Screen Shot 2021-06-09 at 7 34 08 PM

The extra right padding results in a poor reading experience while reading some of tracing's documentation. While I recognize that we're misusing docblocks to render tooltips and #83550 attempted to solve this problem in more well-trodden use-cases, I was hoping that this rendering issue could either be fixed or we can be given a decently stable workaround. Thanks!

Meta

rustc --version --verbose:

❯ rustc --version --verbose
rustc 1.54.0-nightly (e4a603270 2021-06-07)
binary: rustc
commit-hash: e4a60327063e82413eed50a10df3b7d19b77bda0
commit-date: 2021-06-07
host: x86_64-apple-darwin
release: 1.54.0-nightly
LLVM version: 12.0.1
@davidbarsky davidbarsky added the C-bug Category: This is a bug. label Jun 9, 2021
@jyn514
Copy link
Member

jyn514 commented Jun 9, 2021

I agree this is not super supported ... cc @jsha in case you want to take a look, but I'm not sure we want to fix it.

@davidbarsky
Copy link
Contributor Author

A fix isn't really strictly necessary. If we can provide custom CSS to rustdoc and docs.rs where we override .docblock with a tracing-specific selector (or a similar, tracing-scoped approach), that'd also be a great resolution.

@camelid camelid 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 Jul 11, 2021
@GuillaumeGomez
Copy link
Member

I think it's somewhat related to #79677.

@jyn514
Copy link
Member

jyn514 commented Jul 23, 2021

If we can provide custom CSS to rustdoc and docs.rs where we override .docblock with a tracing-specific selector (or a similar, tracing-scoped approach), that'd also be a great resolution.

@davidbarsky Missed this before sorry - this is already stable: https://doc.rust-lang.org/stable/rustdoc/command-line-arguments.html#-e--extend-css-extend-rustdocs-css

@jyn514
Copy link
Member

jyn514 commented Aug 16, 2021

I'm going to close this since there's a stable workaround.

@jyn514 jyn514 closed this as completed Aug 16, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

4 participants