rustdoc: extend warning block for admonitions

In AsciiDoc and GitHub's Markdown, admonitions (a.k.a. callouts or alerts) consist of five types (NOTE, TIP, IMPORTANT, CAUTION, and WARNING).^1 reStructuredText has even more types.^3

However, rustdoc consist only of a warning block.^4 So, at this point, this can be used for purposes other than just warnings. For example, looking at usage examples in the clap crate, I think it's also used for purposes like NOTE or TIP.[^5]

/// <div class="warning">
///
/// **NOTE:** This choice is propagated to all child subcommands.
///
/// </div>
///
/// <div class="warning">
///
/// **NOTE:** Default behaviour is [`ColorChoice::Auto`].
///
/// </div>

I think warning is correct for the first <div>, but note or tip would be more appropriate for the second one. Since Command::color propagates to all child subcommands, overlooking it can cause unintended colors to appear or disappear. Therefore, I think the warning class is appropriate. However, the fact that the default behaviour is ColorChoice::Auto is merely supplementary information. Since this does not lead to any dangerous errors or unintended behavior, I think the warning class is inappropriate.

If representing the above in GitHub's Markdown, I think the second is more appropriate than the first:

[!WARNING]
This choice is propagated to all child subcommands.

[!WARNING]
Default behaviour is ColorChoice::Auto.

[!WARNING]
This choice is propagated to all child subcommands.

[!NOTE]
Default behaviour is ColorChoice::Auto.

If the sole purpose is emphasis, I think just the warning class is sufficient. However, from a semantic standpoint, I don't think it is correct to represent everything using the warning class.

Therefore, I propose adding the note, tip, important, and caution classes to rustdoc.

+/// <div class="note">...</div>
+/// <div class="tip">...</div>
+/// <div class="important">...</div>
+/// <div class="caution">...</div>
/// <div class="warning">...</div>

It seems that these five types are supported by many markup languages, so I proposed them. However, regarding rustdoc, if other types are more appropriate, I think it would be desirable to remove the types I proposed, or add types I didn't propose.

• https://users.rust-lang.org/t/why-do-admonitions-for-rustdoc-consist-only-of-a-warning-block/142455
• #79710

@rustbot label +A-markdown-parsing +C-feature-request +T-rustdoc

[^5]: https://docs.rs/clap/4.6.7/clap/struct.Command.html#method.color

Start with rustdoc's existing warning-block documentation and the markdown-parsing entry points that handle the warning class. Define how note, tip, important, and caution should render alongside warning, then verify the proposed admonition classes in rendered documentation and relevant parser coverage.