Add syntax extension to add warning blocks

@dtolnay

Following #79677, we realized that rustdoc users would prefer to have a syntax extension rather than using plain HTML to have warning blocks.

@dtolnay suggested the following:

/// WARNING: it doesn't work yet.

@Darksonn suggested:

[[info]]
| Many of Tokio's types are named the same as their synchronous equivalent in
| the Rust standard library. When it makes sense, Tokio exposes the same APIs
| as `std` but using `async fn`.

What do you think?

cc @rust-lang/rustdoc

Personal Opinions:
The first style will look fine for short forms, but I'm not sure for longer text. A possible syntax:

/// WARNING: This is a lot of text, continued
///          on multiple lines, and what if I want more formatting, or another block?
///          *this is interesting*

Which to me pushes the text too far right. Not having any spacing, but just separating with newlines, seems hard to parse at a glance what is part of the WARNING, and prevents multiple line breaks inside the warning. Also, it's not as extensible. INFO can be added, but if we ever want more extensions, they would increasingly possibly conflict with other things.
The second style makes it immediately clear what is part of the block, and is unlikely to accidentally conflict if we ever want to add more block styles. It also supports multiple lines or inner blocks trivially. A final advantage is that it may support nested blocks, in case those ever come to be useful.
Overall: I prefer the second form, both aesthetically and for future-proofing

I think I agree with @CraftSpider in preferring the second form. I like the first form's simplicity, but it also seems surprising that WARNING: is treated as a 'keyword' and will change the formatting of the docs.

That's why we have this debate. 😛

I personally actually prefer stabilizing a CSS class, I think we should do more of that, just because parsing can get annoying. But this is not that hard to parse anyway.

The problem with WARNING: is precisely that you can't scope it easily: what if you want to add code blocks? bullet points?

I personally actually prefer stabilizing a CSS class

The problem with this is it ties rustdoc to the HTML backend; like I said on Zulip nothing rustdoc currently does guarentees that it will generate HTML from the markdown. Changing that means that to make the JSON backend have the same info, we'd have to add a full HTML parser to rustdoc just to read the HTML in the markdown, because pulldown does not parse HTML for us. I really think we should avoid making the JSON backend a second-class citizen.

Also there's not much point to this if it's just a little CSS IMO, you can add that yourself with --html-after-content and it will look just as good and be more flexible since you can control the styles yourself.

I'm not a giant fan of the [[info]] syntax because it looks odd when rendered by anything other than rustdoc, which I'd rather avoid, one of the major design concerns for intra-doc links was compatibility with other markdown parsers: https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md#standard-conforming-markdown

The problem with this is it ties rustdoc to the HTML backend

So, I agree, but I'm not convinced that the warning class is something that needs to be surfaced in the JSON backend as anything special.

Also, bear in mind, HTML is a part of markdown: valid HTML (well a subset of HTML) is valid markdown. Users already can <div style=foo>, and they do that in many cases.

Markdown parsers already need to be able to handle HTML. There's nothing new there. Whatever consumes the JSON backend will need to be able to handle that too.

Also there's not much point to this if it's just a little CSS IMO, you can add that yourself with --html-after-content and it will look just as good and be more flexible since you can control the styles yourself.

I mean, yes, in theory, in practice people don't do this because of the barrier to entry (you have to get your tools to use that, including docs.rs)

because pulldown does not parse HTML for us

Also, this is incorrect, pulldown absolutely parses HTML. It has to, like I said valid HTML is valid Markdown. It doesn't parse it thoroughly, I believe you can mess it up with sufficiently complex HTML, but it parses HTML.

What this changes is subtler: up till now you did not need any particular stylesheet to acceptably render rustdoc markdown from the JSON backend on your own (just use your favorite markdown renderer's stylesheet), but now you will need other css classes to handle rendering warnings as warnings.

The problem with WARNING: is precisely that you can't scope it easily: what if you want to add code blocks? bullet points?

I do not agree that this is a problem. I've used Phabricator's implementation of this approach happily and it is by design that warning banners are one paragraph. It is not the intention that you would put entire sections of documentation into a warning banner. They are for a brief callout. It's fine to refer to a subsequent section of the documentation from the callout if needed.

I suppose this is a matter of taste but it's one where I believe the opinionatedness of the syntax is a positive thing.

@jyn514

So I discussed this a bit with @jyn514 on the side, we agree that the effect on the JSON backend isn't major since HTML is already a subset of markdown and docs use HTML already (especially for images and tables).

My position is as follows:

I strictly prefer HTML over some other scoped syntax with nuances people have to learn.
I don't think there's as much value in unscoped syntax

which makes my position "HTML or nothing", basically. I'm not wholly against unscoped single-line syntax. We NOTE: and EXAMPLE: syntax in W3C specs and you invariably need to add more stuff to it (there's an HTML class in these specs for this reason).

Furthermore, Rust has a strong culture of wrapping text, so this means we need WARNING: to work well while wrapped, and that means we're again introducing some form of scoping mechanism (e.g. indenting the text), which editors will have to learn, as well.

I don't know about admonitions specifically but there seems to be something of a community habit to use "magic tags" on fenced code blocks for this sort of features (e.g. github has a suggestion tag), maybe that could be an option? I don't know if pulldown_cmark has a hook for manipulating code blocks but…

So a warning would be

```warning
as much warning text as you want
```

or maybe the tag would be admonition:<type> to leave room for things like note/todo/danger/…

Alternatively, take a gander at how other markdown implementations extend the language for this sort of features? e.g. python-markdown seems to be using !!!<tag> for admonitions.

Using <div class="warning"> is what we agreed upon in https://github.com/rust-lang/rust/pull/106561/files#diff-625c2b4568f0a7b1c8233bee4e602cdd31b6d88bc06d82dbe33590bf213cd41dR265. The debate now is on the look itself.

Auto merge of rust-lang#106561 - GuillaumeGomez:warning-block, r=rustdoc

Auto merge of #106561 - GuillaumeGomez:warning-block, r=rustdoc

Unfortunately .warning isn't great because markdown has a "boundary" when HTML tags are used. I wanted to add a warning indicating that users probably wanted another trait, but intra-doc links don't work (which is the correct behavior per markdown spec).

Works perfectly fine though (well, minus the UI bug I just discovered haha):

I used this code:

/// <div class="warning">
///
/// [bar]
///
/// </div>
pub fn foo() {}

pub fn bar() {}

I'll send a PR to improve documentation.

Ah. Well I suppose the issue wasn't with intra-doc links, but with inline code blocks. What I tried was that but with [`bar`], and it failed.

Works too:

I opened #119245 which adds extra explanation on how to use markdown inside html tags. That should solve your issue.

That note is exactly what I was just looking in to. I had it inline, given my familiarity with HTML. TIL that matters.

It doesn't hurt to have it and if it can helps users, well, why not doing it. :)

Rollup merge of rust-lang#119245 - GuillaumeGomez:improve-docs, r=fmease

Unrolled build for rust-lang#119245

Auto merge of #106561 - GuillaumeGomez:warning-block, r=rustdoc

Navigation Menu

Repository navigation

Add syntax extension to add warning blocks #79710

35 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add syntax extension to add warning blocks #79710

Description

Activity

CraftSpider commented on Dec 4, 2020

camelid commented on Dec 4, 2020

GuillaumeGomez commented on Dec 4, 2020

Manishearth commented on Dec 5, 2020

jyn514 commented on Dec 5, 2020

jyn514 commented on Dec 5, 2020

jyn514 commented on Dec 5, 2020

Manishearth commented on Dec 5, 2020

Manishearth commented on Dec 5, 2020

dtolnay commented on Dec 5, 2020

Manishearth commented on Dec 5, 2020

masklinn commented on Dec 23, 2020

35 remaining items

GuillaumeGomez commented on Jun 24, 2023

jhpratt commented on Dec 23, 2023

GuillaumeGomez commented on Dec 23, 2023

jhpratt commented on Dec 23, 2023

GuillaumeGomez commented on Dec 23, 2023

GuillaumeGomez commented on Dec 23, 2023

jhpratt commented on Dec 23, 2023

GuillaumeGomez commented on Dec 23, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions