Skip to content

Commit e6680a3

Browse files
choldgrafcholdgraf
authored
adding custom admonitions classes (#183)
1 parent 4576172 commit e6680a3

File tree

6 files changed

+187
-67
lines changed

6 files changed

+187
-67
lines changed

‎docs/demo/demo.rst

+20-5
Original file line numberDiff line numberDiff line change
@@ -428,15 +428,30 @@ Admonitions
428428

429429
You can make up your own admonition too.
430430

431-
.. admonition:: If you add a name flag, it will be styled
432-
:name: warning
431+
.. admonition:: If you add a class flag, it will be styled
432+
:class: warning
433433

434434
For example, this admonition block uses the following code:
435435

436436
.. code-block::
437437
438-
.. admonition:: If you add a name flag, it will be styled
439-
:name: warning
438+
.. admonition:: If you add a class flag, it will be styled
439+
:class: warning
440+
441+
Here are a list of classes you can try:
442+
443+
.. code-block::
444+
445+
note
446+
important
447+
tip
448+
attention
449+
caution
450+
warning
451+
danger
452+
error
453+
hint
454+
440455
441456
Topics, Sidebars, and Rubrics
442457
-----------------------------
@@ -499,7 +514,7 @@ HTML
499514
The HTML below shouldn't display, but it uses RequireJS to make sure that all
500515
works as expected. If the widgets don't show up, RequireJS may be broken.
501516

502-
.. jupyter-execute::
517+
.. jupyter-execute::
503518

504519
import plotly.io as pio
505520
import plotly.express as px

‎pydata_sphinx_theme/bootstrap_html_translator.py

-59
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,12 @@
22
"""
33
from docutils import nodes
44

5-
from sphinx.locale import admonitionlabels
65
from sphinx.writers.html5 import HTML5Translator
76
from sphinx.util import logging
87

98
logger = logging.getLogger(__name__)
109

1110

12-
# Mapping of admonition classes to Bootstrap contextual classes
13-
alert_classes = {
14-
"attention": "primary",
15-
"caution": "warning",
16-
"danger": "danger",
17-
"error": "danger",
18-
"hint": "info",
19-
"important": "primary",
20-
"note": "info",
21-
"seealso": "info",
22-
"tip": "primary",
23-
"warning": "warning",
24-
"todo": "info",
25-
"example": "info",
26-
}
27-
28-
2911
class BootstrapHTML5Translator(HTML5Translator):
3012
"""Custom HTML Translator for a Bootstrap-ified Sphinx layout
3113
This is a specialization of the HTML5 Translator of sphinx.
@@ -37,47 +19,6 @@ def __init__(self, *args, **kwds):
3719
super().__init__(*args, **kwds)
3820
self.settings.table_style = "table"
3921

40-
def visit_admonition(self, node, name=""):
41-
# type: (nodes.Element, str) -> None
42-
# copy of sphinx source to add alert classes
43-
classes = ["alert"]
44-
45-
# If we have a generic admonition block, style it as info
46-
if (
47-
any("admonition-" in iclass for iclass in node.attributes["classes"])
48-
and name == ""
49-
):
50-
name = "admonition"
51-
if node.attributes.get("names"):
52-
# If `name` is specified, try to look it up in the list of alerts
53-
alert_name = node.attributes.get("names")[0]
54-
else:
55-
# If no `name` is specified, style it as `note`
56-
alert_name = "note"
57-
if alert_name not in alert_classes:
58-
logger.warning(
59-
f"Unsupported admonition name: `{alert_name}`. Using style `note`.",
60-
location=(self.docnames[0], node.children[0].line),
61-
)
62-
alert_name = "note"
63-
64-
# Add the "admonition" class to alert_classes so that it can be referenced
65-
alert_classes[name] = alert_classes[alert_name]
66-
67-
# Remove the title from this admonition and add it to the admonitionlabels
68-
# Because this is how Sphinx inserts titles into admonitions
69-
title = node.children.pop(0)
70-
admonitionlabels[name] = title.astext()
71-
72-
if name:
73-
classes.append("alert-{0}".format(alert_classes[name]))
74-
75-
# This mimics what Sphinx does in its own `visit_admonition`
76-
# but wraps in `alert`
77-
self.body.append(self.starttag(node, "div", CLASS=" ".join(classes)))
78-
if name:
79-
node.insert(0, nodes.title(name, admonitionlabels[name]))
80-
8122
def visit_table(self, node):
8223
# type: (nodes.Element) -> None
8324
# copy of sphinx source to *not* add 'docutils' and 'align-default' classes

‎pydata_sphinx_theme/static/css/index.css

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/scss/_admonitions.scss

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
2+
.admonition {
3+
margin: 1.5625em 0 !important;
4+
padding: 0 .6rem !important;
5+
overflow: hidden;
6+
page-break-inside: avoid;
7+
border-left: .2rem solid $blue;
8+
border-radius: .1rem;
9+
box-shadow: 0 0.2rem 0.5rem rgba(0,0,0,.05), 0 0 0.05rem rgba(0,0,0,.1);
10+
transition: color 250ms,background-color 250ms,border-color 250ms;
11+
12+
// Last paragraph should have same spacing as title
13+
p:last-child {
14+
margin-bottom: 0.4em;
15+
}
16+
17+
// Defaults for all admonitions
18+
.admonition-title {
19+
position: relative;
20+
margin: 0 -0.6rem !important;
21+
padding: .4rem .6rem .4rem 2rem;
22+
font-weight: 700;
23+
background-color: rgba(68,138,255,.1);
24+
25+
&:before {
26+
position: absolute;
27+
left: .6rem;
28+
width: 1rem;
29+
height: 1rem;
30+
color: $blue;
31+
font-family: "Font Awesome 5 Free";
32+
font-weight: 900;
33+
content: $icon-info-circle; /* info-circle */
34+
}
35+
36+
// Next element after title needs some extra upper-space
37+
+ * {
38+
margin-top: 0.4em;
39+
}
40+
}
41+
42+
&.attention {
43+
border-color: $orange;
44+
.admonition-title {
45+
background-color: $orange-light;
46+
47+
&:before {
48+
color: $orange;
49+
content: $icon-exclamation-circle;
50+
}
51+
}
52+
}
53+
54+
&.caution {
55+
border-color: $orange;
56+
.admonition-title {
57+
background-color: $orange-light;
58+
59+
&:before {
60+
color: $orange;
61+
content: $icon-exclamation-triangle;
62+
}
63+
}
64+
}
65+
66+
&.warning {
67+
border-color: $red;
68+
.admonition-title {
69+
background-color: $red-light;
70+
71+
&:before {
72+
color: $red;
73+
content: $icon-exclamation-triangle;
74+
}
75+
}
76+
}
77+
78+
&.danger {
79+
border-color: $red;
80+
.admonition-title {
81+
background-color: $red-light;
82+
83+
&:before {
84+
color: $red;
85+
content: $icon-exclamation-triangle;
86+
}
87+
}
88+
}
89+
90+
&.error {
91+
border-color: $red;
92+
.admonition-title {
93+
background-color: $red-light;
94+
95+
&:before {
96+
color: $red;
97+
content: $icon-times-circle;
98+
}
99+
}
100+
}
101+
102+
&.hint {
103+
border-color: $yellow;
104+
.admonition-title {
105+
background-color: $yellow-light;
106+
107+
&:before {
108+
color: $yellow;
109+
content: $icon-lightbulb;
110+
}
111+
}
112+
}
113+
114+
&.tip {
115+
border-color: $yellow;
116+
.admonition-title {
117+
background-color: $yellow-light;
118+
119+
&:before {
120+
color: $yellow;
121+
content: $icon-lightbulb;
122+
}
123+
}
124+
}
125+
126+
&.important {
127+
border-color: $blue;
128+
.admonition-title {
129+
background-color: $blue-light;
130+
131+
&:before {
132+
color: $blue;
133+
content: $icon-exclamation-circle;
134+
}
135+
}
136+
}
137+
138+
&.note {
139+
border-color: $blue;
140+
.admonition-title {
141+
background-color: $blue-light;
142+
143+
&:before {
144+
color: $blue;
145+
content: $icon-info-circle;
146+
}
147+
}
148+
}
149+
}

‎src/scss/_variables.scss

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Used by admonitions
2+
$orange-light: #ffedcc;
3+
$red-light: #fdf3f2;
4+
$yellow-light: #fff6dd;
5+
$blue-light: #e7f2fa;
6+
7+
// Icons for admonition titles
8+
$icon-info-circle: "\f05a";
9+
$icon-exclamation-circle: "\f06a";
10+
$icon-lightbulb: "\f0eb";
11+
$icon-question: "\f128";
12+
$icon-exclamation-triangle: "\f071";
13+
$icon-times-circle: "\f057";

‎src/scss/index.scss

+4-2
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,14 @@ $container-max-widths: (
99

1010
// Include core Bootstrap
1111
@import '../../node_modules/bootstrap/scss/bootstrap';
12+
@import './variables';
1213

1314
// Import custom fonts
1415
@import url('https://fonts.googleapis.com/css?family=Open+Sans:400|Lato:400');
1516

1617
@import './base';
1718
@import './navbar';
19+
@import './admonitions';
1820

1921
// Custom css, TODO: to be refactored in different partials
2022
.deprecated {
@@ -83,8 +85,8 @@ table.field-list {
8385
}
8486
}
8587

86-
/**
87-
* Styling for autosummary tables
88+
/**
89+
* Styling for autosummary tables
8890
*/
8991

9092
// The first column (with the signature) should not wrap

0 commit comments

Comments
 (0)