Provide a way to add warning blocks in documentation.

[bIgBV]

Right now, if we want to warn users of a potential panicing API, we need to use html blocks directly within markdown content in order to do so. This results in the following being rendered:

An ecosystem-wide convention of notifying users of potential panic conditions could be really helpful. See this discussion for more information. The main point of this is as follows:

[the] nice thing about having something baked in is that it's everywhere in the ecosystem. people know that if they see some particular icon or something, it means that this box describes what situations a function will panic under (for example).

[nagisa]

I… don’t think markdown really has the annotations necessary to mark arbitrary paragraphs (or any other block-elements) with metadata necessary for this kind of thing. And ultimately its the downside of using markdown for documentation.

I suspect that any kind of solution will involve introducing html into markup, but it could be simplified to something like

<section class="warning">

Anything markdown goes here

</section>

and we could provide the default styling for this in our rustdoc css.

[bIgBV]

Yeah I agree that providing a CSS class would be the simplest way to achieve this.

[GuillaumeGomez]

Yes, this sounds like a good idea and doesn't require much changes either. Want to do it @bIgBV ?

[bIgBV]

Yeah definitely, if you just point me in the right direction, I could probably have something ready by the weekend.

[jyn514]

Take a look at https://github.com/rust-lang/rust/tree/master/src/librustdoc/html/static/themes, I think just modifying the static files should be enough. x.py doc --stage 1 src/libstd will let you try out the changes.

[MathieuDuponchelle]

Just a quick note, while commonmark development is slower than I would wish, there is a discussion opened for a syntax for attributes: https://talk.commonmark.org/t/consistent-attribute-syntax/272/137

[thomcc]

I did this in bytemuck a while ago: https://github.com/Lokathor/bytemuck/blob/6db9c1944b0604171a70e178bcdd1db1a4ce4dd2/src/offset_of.rs#L69-L75, which Renders as https://docs.rs/bytemuck/1.7.0/bytemuck/macro.offset_of.html#usage-with-reprpacked-structs.

The idea came from @nvzqz who does the same stuff in some of his crates.

I think I'd prefer more a more general thing than just warnings, but I'll take what I can get, honestly.

[ShellCode33]

Note

Here's how GitHub does it, I like it a lot:
https://github.com/orgs/community/discussions/16925

[GuillaumeGomez]

It was done in #106561 (issue is #79710). Closing this one then.