add support for GitHub Markdown alerts (#718)

mitmproxy · Jul 24, 2024 · 1f08df5 · 1f08df5
1 parent f2ffa5e
commit 1f08df5
Show file tree

Hide file tree

Showing 32 changed files with 101 additions and 83 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@
 
 - If `example.data.Data` is also exposed as `example.Data`, pdoc now links to `example.Data` in documentation.
   ([#670](https://github.com/mitmproxy/pdoc/pull/670), @nathanthorpe, @mhils)
+- Add support for [GitHub Markdown Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
+  ([#718](https://github.com/mitmproxy/pdoc/pull/718), @mhils)
 - Improve rendering of enums on Python 3.12+.
   ([#708](https://github.com/mitmproxy/pdoc/pull/708), @mhils)
 - Fix a bug where hyperlinks would get parsed as docstring references.

diff --git a/pdoc/docstrings.py b/pdoc/docstrings.py
@@ -427,7 +427,7 @@ def _rst_admonition(m: re.Match[str]) -> str:
             else:
                 heading = ""
             return (
-                f'{ind}<div class="pdoc-alert pdoc-alert-{type}" markdown="1">\n'
+                f'{ind}<div class="alert {type}" markdown="1">\n'
                 f"{heading}"
                 f"{indent(contents, ind)}\n"
                 f"{ind}</div>\n"

diff --git a/pdoc/render_helpers.py b/pdoc/render_helpers.py
@@ -57,6 +57,7 @@
 
 # Keep in sync with the documentation in pdoc/__init__.py!
 markdown_extensions = {
+    "alerts": None,
     "code-friendly": None,
     "cuddled-lists": None,
     "fenced-code-blocks": {"cssclass": formatter.cssclass},

diff --git a/pdoc/templates/content.css b/pdoc/templates/content.css
@@ -27,7 +27,7 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
 
 
 /* Admonitions */
-.pdoc .pdoc-alert {
+.pdoc .alert {
     padding: 1rem 1rem 1rem calc(1.5rem + 24px);
     border: 1px solid transparent;
     border-radius: .25rem;
@@ -36,26 +36,30 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
     margin-bottom: 1rem;
 }
 
-.pdoc .pdoc-alert > *:last-child {
+.pdoc .alert > em {
+    display: none;
+}
+
+.pdoc .alert > *:last-child {
     margin-bottom: 0;
 }
 
 /* Admonitions are currently not stylable via theme.css */
-.pdoc .pdoc-alert-note  {
+.pdoc .alert.note  {
     color: #084298;
     background-color: #cfe2ff;
     border-color: #b6d4fe;
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/info-circle-fill.svg' %}{% endfilter %}");
 }
 
-.pdoc .pdoc-alert-warning {
+.pdoc .alert.warning {
     color: #664d03;
     background-color: #fff3cd;
     border-color: #ffecb5;
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/exclamation-triangle-fill.svg' %}{% endfilter %}");
 }
 
-.pdoc .pdoc-alert-danger {
+.pdoc .alert.danger {
     color: #842029;
     background-color: #f8d7da;
     border-color: #f5c2c7;

diff --git a/test/testdata/ast_parsing.html b/test/testdata/ast_parsing.html
diff --git a/test/testdata/demo.html b/test/testdata/demo.html
diff --git a/test/testdata/demo_eager.html b/test/testdata/demo_eager.html
diff --git a/test/testdata/demo_long.html b/test/testdata/demo_long.html
diff --git a/test/testdata/demo_long.py b/test/testdata/demo_long.py
@@ -261,18 +261,21 @@ def embed_image():
 
 def admonitions():
     """
-    pdoc also supports basic reStructuredText admonitions:
+    pdoc also supports basic reStructuredText admonitions or GitHub's Markdown alerts:
 
     ```
+    > [!NOTE/WARNING/DANGER]
+    > Useful information that users should know, even when skimming content.
+
     .. note/warning/danger:: Optional title
        Body text
     ```
 
-    .. note::
-       Hi there!
+    > [!NOTE]
+    > Hi there!
 
     .. warning:: Be Careful!
-       This warning has both a title and content.
+       This warning has both a title *and* content.
 
     .. danger::
        Danger ahead.

diff --git a/test/testdata/demopackage.html b/test/testdata/demopackage.html
diff --git a/test/testdata/demopackage_dir.html b/test/testdata/demopackage_dir.html
diff --git a/test/testdata/enums.html b/test/testdata/enums.html
diff --git a/test/testdata/example_customtemplate.html b/test/testdata/example_customtemplate.html
diff --git a/test/testdata/example_darkmode.html b/test/testdata/example_darkmode.html
diff --git a/test/testdata/example_mkdocs.html b/test/testdata/example_mkdocs.html
diff --git a/test/testdata/flavors_google.html b/test/testdata/flavors_google.html
diff --git a/test/testdata/flavors_numpy.html b/test/testdata/flavors_numpy.html
diff --git a/test/testdata/flavors_rst.html b/test/testdata/flavors_rst.html
diff --git a/test/testdata/math_demo.html b/test/testdata/math_demo.html
diff --git a/test/testdata/math_misc.html b/test/testdata/math_misc.html
diff --git a/test/testdata/mermaid_demo.html b/test/testdata/mermaid_demo.html
diff --git a/test/testdata/misc.html b/test/testdata/misc.html
diff --git a/test/testdata/misc_py310.html b/test/testdata/misc_py310.html
diff --git a/test/testdata/misc_py311.html b/test/testdata/misc_py311.html
diff --git a/test/testdata/misc_py312.html b/test/testdata/misc_py312.html
diff --git a/test/testdata/misc_py39.html b/test/testdata/misc_py39.html
diff --git a/test/testdata/pyo3_sample_library.html b/test/testdata/pyo3_sample_library.html
diff --git a/test/testdata/render_options.html b/test/testdata/render_options.html
diff --git a/test/testdata/top_level_reimports.html b/test/testdata/top_level_reimports.html
diff --git a/test/testdata/type_checking_imports.html b/test/testdata/type_checking_imports.html
diff --git a/test/testdata/type_stub.html b/test/testdata/type_stub.html
diff --git a/test/testdata/visibility.html b/test/testdata/visibility.html