adding custom admonitions classes (#183)

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
+      .. admonition:: If you add a class flag, it will be styled
+         :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

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

src/scss/_admonitions.scss

@@ -0,0 +1,149 @@
+// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
+.admonition {
+  margin: 1.5625em 0 !important;
+  padding: 0 .6rem !important;
+  overflow: hidden;
+  page-break-inside: avoid;
+  border-left: .2rem solid $blue;
+  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: $blue;
+      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: $orange;
+    .admonition-title {
+      background-color: $orange-light;
+
+      &:before {
+        color: $orange;
+        content: $icon-exclamation-circle;
+      }
+    }
+  }
+
+  &.caution {
+    border-color: $orange;
+    .admonition-title {
+      background-color: $orange-light;
+
+      &:before {
+        color: $orange;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.warning {
+    border-color: $red;
+    .admonition-title {
+      background-color: $red-light;
+
+      &:before {
+        color: $red;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.danger {
+    border-color: $red;
+    .admonition-title {
+      background-color: $red-light;
+
+      &:before {
+        color: $red;
+        content: $icon-exclamation-triangle;
+      }
+    }
+  }
+
+  &.error {
+    border-color: $red;
+    .admonition-title {
+      background-color: $red-light;
+
+      &:before {
+        color: $red;
+        content: $icon-times-circle;
+      }
+    }
+  }
+
+  &.hint {
+    border-color: $yellow;
+    .admonition-title {
+      background-color: $yellow-light;
+
+      &:before {
+        color: $yellow;
+        content: $icon-lightbulb;
+      }
+    }
+  }
+
+  &.tip {
+    border-color: $yellow;
+    .admonition-title {
+      background-color: $yellow-light;
+
+      &:before {
+        color: $yellow;
+        content: $icon-lightbulb;
+      }
+    }
+  }
+
+  &.important {
+    border-color: $blue;
+    .admonition-title {
+      background-color: $blue-light;
+
+      &:before {
+        color: $blue;
+        content: $icon-exclamation-circle;
+      }
+    }
+  }
+
+  &.note {
+    border-color: $blue;
+    .admonition-title {
+      background-color: $blue-light;
+
+      &:before {
+        color: $blue;
+        content: $icon-info-circle;
+      }
+    }
+  }
+}

src/scss/_variables.scss

@@ -0,0 +1,13 @@
+// Used by admonitions
+$orange-light: #ffedcc;
+$red-light: #fdf3f2;
+$yellow-light: #fff6dd;
+$blue-light: #e7f2fa;
+
+// Icons for admonition titles
+$icon-info-circle: "\f05a";
+$icon-exclamation-circle: "\f06a";
+$icon-lightbulb: "\f0eb";
+$icon-question: "\f128";
+$icon-exclamation-triangle: "\f071";
+$icon-times-circle: "\f057";

src/scss/index.scss

@@ -9,12 +9,14 @@ $container-max-widths: (
 
 // Include core Bootstrap
 @import '../../node_modules/bootstrap/scss/bootstrap';
+@import './variables';
 
 // Import custom fonts
 @import url('https://fonts.googleapis.com/css?family=Open+Sans:400|Lato:400');
 
 @import './base';
 @import './navbar';
+@import './admonitions';
 
 // Custom css, TODO: to be refactored in different partials
 .deprecated {
@@ -83,8 +85,8 @@ table.field-list {
   }
 }
 
-/**		
- * Styling for autosummary tables		
+/**
+ * Styling for autosummary tables
  */
 
 // The first column (with the signature) should not wrap