Skip to content

Provide a way to add warning blocks in documentation. #73935

Closed
Closed
Provide a way to add warning blocks in documentation.#73935
Assignees
GuillaumeGomez
Labels
A-markdown-parsingArea: Markdown parsing for doc-commentsC-feature-requestCategory: A feature request, i.e: not implemented / a PR.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Description

@bIgBV
bIgBV
opened on Jul 1, 2020

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:

Screen Shot 2020-07-01 at 11 22 29 AM

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).

Activity

  1. jonas-schievink
    added
    C-feature-requestCategory: A feature request, i.e: not implemented / a PR.
    T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
    on Jul 1, 2020

  2. nagisa commented on Jul 4, 2020

    @nagisa
    nagisa
    on Jul 4, 2020
    Member

    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.

  3. bIgBV commented on Jul 4, 2020

    @bIgBV
    bIgBV
    on Jul 4, 2020
    Author

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

  4. GuillaumeGomez commented on Jul 9, 2020

    @GuillaumeGomez
    GuillaumeGomez
    on Jul 9, 2020
    Member

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

  5. bIgBV commented on Jul 14, 2020

    @bIgBV
    bIgBV
    on Jul 14, 2020
    Author

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

  6. jyn514 commented on Jul 30, 2020

    @jyn514
    jyn514
    on Jul 30, 2020
    Member

    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.

  7. jyn514
    added
    A-markdown-parsingArea: Markdown parsing for doc-comments
    on Nov 12, 2020
  8. GuillaumeGomez
    self-assigned this
    on Dec 3, 2020

  9. MathieuDuponchelle commented on Jun 11, 2021

    @MathieuDuponchelle
    MathieuDuponchelle
    on Jun 11, 2021

    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

  10. thomcc commented on Jul 5, 2021

    @thomcc
    thomcc
    on Jul 5, 2021
    Member

    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.

  11. ShellCode33 commented on Jan 27, 2024

    @ShellCode33
    ShellCode33
    on Jan 27, 2024

    Note

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

  12. GuillaumeGomez commented on Jan 27, 2024

    @GuillaumeGomez
    GuillaumeGomez
    on Jan 27, 2024
    Member

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

  13. GuillaumeGomez
    closed this as completedon Jan 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

A-markdown-parsingArea: Markdown parsing for doc-commentsC-feature-requestCategory: A feature request, i.e: not implemented / a PR.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions