Use existing admonition tags and classes in new GFM admonitions

[flying-sheep]

In #374 you added admoniton support but didn’t match the existing rST HTML structure that exists in many READMEs on PyPI already.

We should change that and emit the existing structure instead so existing READMEs can benefit from the new to-be-added styling.

e.g. for django-push-notifications, this

.. note::
	To migrate from legacy FCM APIs to HTTP v1, see `docs/FCM <https://github.com/jazzband/django-push-notifications/blob/master/docs/FCM.rst>`_.

becomes this HTML

<aside class="admonition note">
<p class="admonition-title">Note</p>
<p>To migrate from legacy FCM APIs to HTTP v1, see <a href="https://github.com/jazzband/django-push-notifications/blob/master/docs/FCM.rst" rel="nofollow">docs/FCM</a>.</p>
</aside>

and renders as

the classes in this PR should be adjusted to match the rST classes that already exist before adding support.

cc @miketheman @ewdurbin

[miketheman]

For clarification, that PR was to enable GFM admonitions, not to support RST ones that are already supported.

[flying-sheep]

It’s the same feature in two different markup languages.

We should emit the same HTML for both.

We’re already emitting <aside/>s with the two classes “admonition” and ”admonition type”, so the new GFM admonition should match that existing HTML representation.

In other words, before the next release, we should modify the test file like so and change what we do until the test passes.

diff --git a/tests/fixtures/test_GFM_alerts.html b/tests/fixtures/test_GFM_alerts.html
index a483d93..06bc248 100644
--- a/tests/fixtures/test_GFM_alerts.html
+++ b/tests/fixtures/test_GFM_alerts.html
@@ -1,23 +1,23 @@
 <h1><a href="#user-content-github-alerts" id="user-content-github-alerts" rel="nofollow"></a>GitHub Alerts</h1>
 <p>Also known as callouts and admonitions.</p>
-<div class="markdown-alert markdown-alert-note">
-<p class="markdown-alert-title">Note</p>
+<aside class="admonition note">
+<p class="admonition-title">Note</p>
 <p>Useful information that users should know, even when skimming content.</p>
-</div>
-<div class="markdown-alert markdown-alert-tip">
-<p class="markdown-alert-title">Tip</p>
+</aside>
+<aside class="admonition tip">
+<p class="admonition-title">Tip</p>
 <p>Helpful advice for doing things better or more easily.</p>
-</div>
-<div class="markdown-alert markdown-alert-important">
-<p class="markdown-alert-title">Important</p>
+</aside>
+<aside class="admonition important">
+<p class="admonition-title">Important</p>
 <p>Key information users need to know to achieve their goal.</p>
-</div>
-<div class="markdown-alert markdown-alert-warning">
-<p class="markdown-alert-title">Warning</p>
+</aside>
+<aside class="admonition warning">
+<p class="admonition-title">Warning</p>
 <p>Urgent info that needs immediate user attention to avoid problems.</p>
-</div>
-<div class="markdown-alert markdown-alert-caution">
-<p class="markdown-alert-title">Caution</p>
+</aside>
+<aside class="admonition caution">
+<p class="admonition-title">Caution</p>
 <p>Advises about risks or negative outcomes of certain actions.</p>
-</div>
+</aside>
 <p><a href="https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts" rel="nofollow">Source reference</a></p>

[miketheman]

Okay, send a PR and let's see how much complexity that adds, vs adding similar alias classes in css on warehouse side.

[flying-sheep]

Sure! I’ll do a transform using html.parser and try to get an option into comrak to make that transform obsolete in the future. Then we can set the minimum version and that option and delete the transform again. Sounds good?

/edit: both PRs are done. Since the option will probably take some time to get merged, released, percolate to the python project, and be released there, I think having the temporary transform in before the next readme_renderer release would be a good idea.