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.

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

Strip leading trailing empty lines in doc code blocks #103376

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

GuillaumeGomez
Copy link
Member

Fixes #102996.

We currently have an inconsistent way of handling leading and trailing empty lines in doc code blocks (some examples in the linked issue). With this PR, I propose to remove all of them, whether there is hidden code or not. So for example:

```

let x = 12;
 
# hello
```

will be rendered like this:

```
let x = 12;
```

What do you think @rust-lang/rustdoc ?

@GuillaumeGomez GuillaumeGomez added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Oct 21, 2022
@rust-highfive
Copy link
Collaborator

r? @notriddle

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

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 21, 2022

<span class="comment">// bye</span></code></pre></div>
"#,
);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a test case with boring lines at the start and end, since these are the use cases that actually motivate this feature.

        t(
            "\
```
# hello


f();


# goodbye
```",
            r#"
<div class="example-wrap"><pre class="rust rust-example-rendered"><code>f();</code></pre></div>
"#,
        );

@notriddle
Copy link
Contributor

On a broader note, I don't really like this approach, since the CommonMark spec specifically says that empty lines in fenced code blocks are supposed to be preserved, even if the entire code block is nothing but newlines.

But it probably doesn't matter in practice.

@GuillaumeGomez
Copy link
Member Author

Hence why I'm asking everyone's opinion on this. This is the simplest approach but we can also only remove commented lines and keep all the others or have a mix and remove lines if it starts or ends with commented lines.

@bors
Copy link
Contributor

bors commented Dec 11, 2022

☔ The latest upstream changes (presumably #105554) made this pull request unmergeable. Please resolve the merge conflicts.

@Dylan-DPC Dylan-DPC added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

rustdoc: inconsistent number of blank lines rendered top/bottom
5 participants