diff --git a/CHANGELOG.md b/CHANGELOG.md index 22519608..4e99fbcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ # Unreleased: pdoc next + - Improve display of reStructuredText admonitions. + ([#372](https://github.com/mitmproxy/pdoc/issues/372), [@mhils](https://github.com/mhils)) - Add support for reStructuredText field lists: `:param foo: text`. ([#275](https://github.com/mitmproxy/pdoc/issues/275), [@mhils](https://github.com/mhils)) diff --git a/pdoc/docstrings.py b/pdoc/docstrings.py index f5266974..95724cb4 100644 --- a/pdoc/docstrings.py +++ b/pdoc/docstrings.py @@ -328,10 +328,17 @@ def _rst_admonition(m: re.Match[str]) -> str: return indent(included, ind) if type == "math": return f"{ind}$${val}{contents}$$\n" - if type == "note": - text = val or "Note" - elif type == "warning": - text = val or "Warning" + if type in ("note", "warning", "danger"): + if val: + heading = f"{ind}###### {val}\n" + else: + heading = "" + return ( + f'{ind}
\n' + f"{heading}" + f"{indent(contents, ind)}\n" + f"{ind}
\n" + ) elif type == "versionadded": text = f"New in version {val}" elif type == "versionchanged": @@ -348,9 +355,7 @@ def _rst_admonition(m: re.Match[str]) -> str: return text - admonition = ( - "note|warning|versionadded|versionchanged|deprecated|seealso|math|include" - ) + admonition = "note|warning|danger|versionadded|versionchanged|deprecated|seealso|math|include" return re.sub( rf""" ^(?P[ ]*)\.\.[ ]+(?P{admonition})::(?P.*) diff --git a/pdoc/render_helpers.py b/pdoc/render_helpers.py index 94cc80b3..ee875626 100644 --- a/pdoc/render_helpers.py +++ b/pdoc/render_helpers.py @@ -44,6 +44,7 @@ "fenced-code-blocks": {"cssclass": formatter.cssclass}, "footnotes": None, "header-ids": None, + "markdown-in-html": None, "pyshell": None, "strike": None, "tables": None, diff --git a/pdoc/templates/content.css b/pdoc/templates/content.css index 1d8538f7..54476da0 100644 --- a/pdoc/templates/content.css +++ b/pdoc/templates/content.css @@ -24,6 +24,43 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when transition: 100ms all; } + +/* Admonitions */ +.pdoc .pdoc-alert { + padding: 1rem 1rem 1rem calc(1.5rem + 24px); + border: 1px solid transparent; + border-radius: .25rem; + background-repeat: no-repeat; + background-position: 1rem center; + margin-bottom: 1rem; +} + +.pdoc .pdoc-alert > *:last-child { + margin-bottom: 0; +} + +/* Admonitions are currently not stylable via theme.css */ +.pdoc .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 { + 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 { + color: #842029; + background-color: #f8d7da; + border-color: #f5c2c7; + background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/lightning-fill.svg' %}{% endfilter %}"); +} + .pdoc .visually-hidden { position: absolute !important; width: 1px !important; diff --git a/pdoc/templates/resources/exclamation-triangle-fill.svg b/pdoc/templates/resources/exclamation-triangle-fill.svg new file mode 100644 index 00000000..3227299e --- /dev/null +++ b/pdoc/templates/resources/exclamation-triangle-fill.svg @@ -0,0 +1 @@ + diff --git a/pdoc/templates/resources/info-circle-fill.svg b/pdoc/templates/resources/info-circle-fill.svg new file mode 100644 index 00000000..612c2579 --- /dev/null +++ b/pdoc/templates/resources/info-circle-fill.svg @@ -0,0 +1 @@ + diff --git a/pdoc/templates/resources/lightning-fill.svg b/pdoc/templates/resources/lightning-fill.svg new file mode 100644 index 00000000..d9edbcaf --- /dev/null +++ b/pdoc/templates/resources/lightning-fill.svg @@ -0,0 +1 @@ + diff --git a/test/testdata/demo.html b/test/testdata/demo.html index 8a454354..01859ef8 100644 --- a/test/testdata/demo.html +++ b/test/testdata/demo.html @@ -10,7 +10,7 @@ - +