search

pypa / readme_renderer

Safely render long_description/README files in Warehouse
Apache License 2.0
158 stars 89 forks source link

Support standard rst admonitions #132

Closed anntzer closed 2 years ago

anntzer commented 6 years ago

rst provides standard "admonitions" (http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions) such as

.. note::
   Hello world!

which gets rendered by default (by rst2html) as screenshot_20181024_142909 but readme_renderer just yields two paragraphs with no markup at all

<div>
<p>Note</p>
<p>Hello, world!</p>
</div>

It would be nice if admonitions were supported. Perhaps related to #120.

donjar commented 6 years ago

I have played around, and it seems that the rendered HTML by default is

<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Hello, world!</p>
</div>

So I believe if we whitelist admonition and the admonition classes in div ("attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"), and first, admonition-title, last in p in the referenced PR, it should work.

kdeldycke commented 4 years ago

This is a great feature to support. It allows package maintainer to display big warning for major package update or breaking changes.

For instance, I use a .. DANGER:: admonition at the very top of my package to announce a renaming:

stuij commented 4 years ago

I'm just adding a +1 in support for this feature.

We have a lot of notes in our ABI docs (current docs up on Github and future docs that will be added), and right now the rendering of them on Github is confusing because of this:

https://github.com/ARM-software/abi-aa

Can we expect any chance of this being supported? It would be really appreciated.

pzhlkj6612 commented 3 years ago

Hi @stuij .

We have a lot of notes in our ABI docs (current docs up on Github and future docs that will be added), and right now the rendering of them on Github is confusing because of this...

Since you mentioned GitHub, I think that what you said is not related to this issue or even this repo. You could have a look at https://github.com/github/markup/issues/68 .