Repository: pypa/readme_renderer (language: python)

Issue:
Support standard rst admonitions
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](https://user-images.githubusercontent.com/1322974/47430333-486ef700-d799-11e8-96b1-06cb674c67cb.png)
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.


Discussion / hints:
I have played around, and it seems that the rendered HTML by default is
```html
<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.
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:
* https://github.com/kdeldycke/maildir-deduplicate/commit/ebfafa153562e093fb060df7d44999b327bfa93d
* https://pypi.org/project/maildir-deduplicate/2.2.0/
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.
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 .

Fix patch:
diff --git a/readme_renderer/clean.py b/readme_renderer/clean.py
index 042883c..332dd5b 100644
--- a/readme_renderer/clean.py
+++ b/readme_renderer/clean.py
@@ -47,7 +47,7 @@
     "span": ["class"],
     "th": ["align"],
     "td": ["align"],
-    "div": ["align"],
+    "div": ["align", "class"],
     "h1": ["align"],
     "h2": ["align"],
     "h3": ["align"],
@@ -55,7 +55,7 @@
     "h5": ["align"],
     "h6": ["align"],
     "code": ["class"],
-    "p": ["align"],
+    "p": ["align", "class"],
     "ol": ["start"],
     "input": ["type", "checked", "disabled"],
 }


Test patch:
diff --git a/tests/fixtures/test_rst_003.html b/tests/fixtures/test_rst_003.html
index e135ee9..17cefc9 100644
--- a/tests/fixtures/test_rst_003.html
+++ b/tests/fixtures/test_rst_003.html
@@ -1,8 +1,8 @@
-<div id="required-packages">
+<div class="section" id="required-packages">
 <h2>Required packages</h2>
 <p>To run the PyPI software, you need Python 2.5+ and PostgreSQL</p>
 </div>
-<div id="quick-development-setup">
+<div class="section" id="quick-development-setup">
 <h2>Quick development setup</h2>
 <p>Make sure you are sitting</p>
 </div>
diff --git a/tests/fixtures/test_rst_admonitions.html b/tests/fixtures/test_rst_admonitions.html
new file mode 100644
index 0000000..f35589f
--- /dev/null
+++ b/tests/fixtures/test_rst_admonitions.html
@@ -0,0 +1,13 @@
+<div class="admonition danger">
+<p class="first admonition-title">!DANGER!</p>
+<p class="last">Will Robinson</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">F Sharp is a note, right?</p>
+</div>
+<div class="admonition admonition-see-also">
+<p class="first admonition-title">See also</p>
+<p class="last">A customized admonition.
+Read more at <a href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions" rel="nofollow">docutils</a></p>
+</div>
diff --git a/tests/fixtures/test_rst_admonitions.rst b/tests/fixtures/test_rst_admonitions.rst
new file mode 100644
index 0000000..9de1da7
--- /dev/null
+++ b/tests/fixtures/test_rst_admonitions.rst
@@ -0,0 +1,11 @@
+.. danger:: Will Robinson
+
+.. note::
+
+   F Sharp is a note, right?
+
+
+.. admonition:: See also
+
+   A customized admonition.
+   Read more at `docutils <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`_
diff --git a/tests/fixtures/test_rst_docinfo.html b/tests/fixtures/test_rst_docinfo.html
index 7718e63..9a34ce9 100644
--- a/tests/fixtures/test_rst_docinfo.html
+++ b/tests/fixtures/test_rst_docinfo.html
@@ -14,6 +14,6 @@
 <td>© 2017, 2018 Lele Gaifax</td></tr>
 </tbody>
 </table>
-<div id="pg-query">
+<div class="section" id="pg-query">
 <h2>pg_query</h2>
 </div>
diff --git a/tests/fixtures/test_rst_linkify.html b/tests/fixtures/test_rst_linkify.html
index b1864dd..e924e12 100644
--- a/tests/fixtures/test_rst_linkify.html
+++ b/tests/fixtures/test_rst_linkify.html
@@ -7,7 +7,7 @@
 <p>It requires a spatial databases compatible with <a href="https://docs.djangoproject.com/en/dev/ref/contrib/gis/" rel="nofollow">GeoDjango</a>.  <a href="http://www.postgresql.org" rel="nofollow">PostgreSQL</a> 9.x
 and <a href="http://postgis.refractions.net" rel="nofollow">PostGIS</a> 2.x are recommended for development and production, since these
 support all the GeoDjango features.</p>
-<div id="status">
+<div class="section" id="status">
 <h2>Status</h2>
 <p>multigtfs is ready for your GTFS project.</p>
 <p>Point releases (0.4.1 to 0.4.2) should be safe, only adding features or fixing
@@ -25,11 +25,11 @@ <h2>Status</h2>
 archive feeds).  If you find a feed that doesn’t work, <a href="https://github.com/tulsawebdevs/django-multi-gtfs/issues" rel="nofollow">file a bug</a>!</p>
 <p>See the <a href="https://github.com/tulsawebdevs/django-multi-gtfs/issues?state=open" rel="nofollow">issues list</a> for more details on bugs and feature requests.</p>
 </div>
-<div id="example-project">
+<div class="section" id="example-project">
 <h2>Example project</h2>
 <p>Check out the <a href="examples/explore/README.md" rel="nofollow">example project</a>.</p>
 </div>
-<div id="development">
+<div class="section" id="development">
 <h2>Development</h2>
 <table>
 <colgroup><col>