adding custom admonitions classes

pydata · May 21, 2020 · 4b2b528 · 4b2b528
1 parent 4a33ff5
commit 4b2b528
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 64 deletions.
diff --git a/docs/demo/demo.rst b/docs/demo/demo.rst
@@ -428,15 +428,30 @@ Admonitions
 
    You can make up your own admonition too.
 
-.. admonition:: If you add a name flag, it will be styled
-   :name: warning
+.. admonition:: If you add a class flag, it will be styled
+   :class: warning
 
    For example, this admonition block uses the following code:
 
    .. code-block::
 
       .. admonition:: If you add a name flag, it will be styled
-         :name: warning
+         :class: warning
+
+   Here are a list of classes you can try:
+
+   .. code-block::
+
+      note
+      important
+      tip
+      attention
+      caution
+      warning
+      danger
+      error
+      hint
+
 
 Topics, Sidebars, and Rubrics
 -----------------------------
@@ -499,7 +514,7 @@ HTML
 The HTML below shouldn't display, but it uses RequireJS to make sure that all
 works as expected. If the widgets don't show up, RequireJS may be broken.
 
-.. jupyter-execute:: 
+.. jupyter-execute::
 
    import plotly.io as pio
    import plotly.express as px

diff --git a/pydata_sphinx_theme/bootstrap_html_translator.py b/pydata_sphinx_theme/bootstrap_html_translator.py
@@ -2,30 +2,12 @@
 """
 from docutils import nodes
 
-from sphinx.locale import admonitionlabels
 from sphinx.writers.html5 import HTML5Translator
 from sphinx.util import logging
 
 logger = logging.getLogger(__name__)
 
 
-# Mapping of admonition classes to Bootstrap contextual classes
-alert_classes = {
-    "attention": "primary",
-    "caution": "warning",
-    "danger": "danger",
-    "error": "danger",
-    "hint": "info",
-    "important": "primary",
-    "note": "info",
-    "seealso": "info",
-    "tip": "primary",
-    "warning": "warning",
-    "todo": "info",
-    "example": "info",
-}
-
-
 class BootstrapHTML5Translator(HTML5Translator):
     """Custom HTML Translator for a Bootstrap-ified Sphinx layout
     This is a specialization of the HTML5 Translator of sphinx.
@@ -37,47 +19,6 @@ def __init__(self, *args, **kwds):
         super().__init__(*args, **kwds)
         self.settings.table_style = "table"
 
-    def visit_admonition(self, node, name=""):
-        # type: (nodes.Element, str) -> None
-        # copy of sphinx source to add alert classes
-        classes = ["alert"]
-
-        # If we have a generic admonition block, style it as info
-        if (
-            any("admonition-" in iclass for iclass in node.attributes["classes"])
-            and name == ""
-        ):
-            name = "admonition"
-            if node.attributes.get("names"):
-                # If `name` is specified, try to look it up in the list of alerts
-                alert_name = node.attributes.get("names")[0]
-            else:
-                # If no `name` is specified, style it as `note`
-                alert_name = "note"
-            if alert_name not in alert_classes:
-                logger.warning(
-                    f"Unsupported admonition name: `{alert_name}`. Using style `note`.",
-                    location=(self.docnames[0], node.children[0].line),
-                )
-                alert_name = "note"
-
-            # Add the "admonition" class to alert_classes so that it can be referenced
-            alert_classes[name] = alert_classes[alert_name]
-
-            # Remove the title from this admonition and add it to the admonitionlabels
-            # Because this is how Sphinx inserts titles into admonitions
-            title = node.children.pop(0)
-            admonitionlabels[name] = title.astext()
-
-        if name:
-            classes.append("alert-{0}".format(alert_classes[name]))
-
-        # This mimics what Sphinx does in its own `visit_admonition`
-        # but wraps in `alert`
-        self.body.append(self.starttag(node, "div", CLASS=" ".join(classes)))
-        if name:
-            node.insert(0, nodes.title(name, admonitionlabels[name]))
-
     def visit_table(self, node):
         # type: (nodes.Element) -> None
         # copy of sphinx source to *not* add 'docutils' and 'align-default' classes

diff --git a/pydata_sphinx_theme/static/css/index.css b/pydata_sphinx_theme/static/css/index.css
diff --git a/src/scss/_base.scss b/src/scss/_base.scss
@@ -110,3 +110,160 @@ pre {
   margin: 1.5em 0 1.5em 0;
   box-shadow: 1px 1px 1px #d8d8d8;
 }
+
+// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
+$icon-info-circle: "\f05a";
+$icon-exclamation-circle: "\f06a";
+$icon-lightbulb: "\f0eb";
+$icon-question: "\f128";
+$icon-exclamation-triangle: "\f071";
+$icon-times-circle: "\f057";
+
+.admonition {
+  margin: 1.5625em 0 !important;
+  padding: 0 .6rem !important;
+  overflow: hidden;
+  page-break-inside: avoid;
+  border-left: .2rem solid #448aff;
+  border-radius: .1rem;
+  box-shadow: 0 0.2rem 0.5rem rgba(0,0,0,.05), 0 0 0.05rem rgba(0,0,0,.1);
+  transition: color 250ms,background-color 250ms,border-color 250ms;
+
+  // Last paragraph should have same spacing as title
+  p:last-child {
+    margin-bottom: 0.4em;
+  }
+
+  // Defaults for all admonitions
+  .admonition-title {
+    position: relative;
+    margin: 0 -0.6rem !important;
+    padding: .4rem .6rem .4rem 2rem;
+    font-weight: 700;
+    background-color: rgba(68,138,255,.1);
+
+    &:before {
+      position: absolute;
+      left: .6rem;
+      width: 1rem;
+      height: 1rem;
+      color: #448aff;
+      font-family: "Font Awesome 5 Free";
+      font-weight: 900;
+      content: $icon-info-circle;  /* info-circle */
+    }
+
+    // Next element after title needs some extra upper-space
+    + * {
+      margin-top: 0.4em;
+    }
+  }
+
+  &.attention {
+    border-color: #f0b37e;
+    .admonition-title {
+      background-color: #ffedcc;
+
+      &:before {
+        color: #f0b37e;
+        content: $icon-exclamation-circle;
+      }
+    }
+  }
+
+  &.caution {
+    border-color: #f0b37e;
+    .admonition-title {
+      background-color: #ffedcc;
+
+      &:before {
+        color: #f0b37e;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.warning {
+    border-color: #f29f97;
+    .admonition-title {
+      background-color: #fdf3f2;
+
+      &:before {
+        color: #f29f97;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.danger {
+    border-color: #f29f97;
+    .admonition-title {
+      background-color: #fdf3f2;
+
+      &:before {
+        color: #f29f97;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.error {
+    border-color: #f29f97;
+    .admonition-title {
+      background-color: #fdf3f2;
+
+      &:before {
+        color: #f29f97;
+        content: $icon-times-circle;
+      }
+    }
+  }
+
+  &.hint {
+    border-color: #1abc9c;
+    .admonition-title {
+      background-color: #dbfaf4;
+
+      &:before {
+        color: #1abc9c;
+        content: $icon-lightbulb;
+      }
+    }
+  }
+
+  &.tip {
+    border-color: #1abc9c;
+    .admonition-title {
+      background-color: #dbfaf4;
+
+      &:before {
+        color: #1abc9c;
+        content: $icon-lightbulb;
+      }
+    }
+  }
+
+  &.important {
+    border-color: #6ab0de;
+    .admonition-title {
+      background-color: #e7f2fa;
+
+      &:before {
+        color: #6ab0de;
+        content: $icon-exclamation-circle;
+      }
+    }
+  }
+
+  &.note {
+    border-color: #6ab0de;
+    .admonition-title {
+      background-color: #e7f2fa;
+
+      &:before {
+        color: #6ab0de;
+        content: $icon-info-circle;
+      }
+    }
+  }
+}