Skip to content

Commit c7c3cec

Browse files
choldgrafcholdgraf
committed
adding custom admonitions classes
1 parent 4a33ff5 commit c7c3cec

File tree

4 files changed

+177
-63
lines changed

4 files changed

+177
-63
lines changed

‎docs/demo/demo.rst

+19-4
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
438438
.. admonition:: If you add a name flag, it will be styled
439-
:name: warning
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

-58
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,6 @@
99
logger = logging.getLogger(__name__)
1010

1111

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-
2912
class BootstrapHTML5Translator(HTML5Translator):
3013
"""Custom HTML Translator for a Bootstrap-ified Sphinx layout
3114
This is a specialization of the HTML5 Translator of sphinx.
@@ -37,47 +20,6 @@ def __init__(self, *args, **kwds):
3720
super().__init__(*args, **kwds)
3821
self.settings.table_style = "table"
3922

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-
8123
def visit_table(self, node):
8224
# type: (nodes.Element) -> None
8325
# 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/_base.scss

+157
Original file line numberDiff line numberDiff line change
@@ -110,3 +110,160 @@ pre {
110110
margin: 1.5em 0 1.5em 0;
111111
box-shadow: 1px 1px 1px #d8d8d8;
112112
}
113+
114+
// Admonitions CSS inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
115+
$icon-info-circle: "\f05a";
116+
$icon-exclamation-circle: "\f06a";
117+
$icon-lightbulb: "\f0eb";
118+
$icon-question: "\f128";
119+
$icon-exclamation-triangle: "\f071";
120+
$icon-times-circle: "\f057";
121+
122+
.admonition {
123+
margin: 1.5625em 0 !important;
124+
padding: 0 .6rem !important;
125+
overflow: hidden;
126+
page-break-inside: avoid;
127+
border-left: .2rem solid #448aff;
128+
border-radius: .1rem;
129+
box-shadow: 0 0.2rem 0.5rem rgba(0,0,0,.05), 0 0 0.05rem rgba(0,0,0,.1);
130+
transition: color 250ms,background-color 250ms,border-color 250ms;
131+
132+
// Last paragraph should have same spacing as title
133+
p:last-child {
134+
margin-bottom: 0.4em;
135+
}
136+
137+
// Defaults for all admonitions
138+
.admonition-title {
139+
position: relative;
140+
margin: 0 -0.6rem !important;
141+
padding: .4rem .6rem .4rem 2rem;
142+
font-weight: 700;
143+
background-color: rgba(68,138,255,.1);
144+
145+
&:before {
146+
position: absolute;
147+
left: .6rem;
148+
width: 1rem;
149+
height: 1rem;
150+
color: #448aff;
151+
font-family: "Font Awesome 5 Free";
152+
font-weight: 900;
153+
content: $icon-info-circle; /* info-circle */
154+
}
155+
156+
// Next element after title needs some extra upper-space
157+
+ * {
158+
margin-top: 0.4em;
159+
}
160+
}
161+
162+
&.attention {
163+
border-color: #f0b37e;
164+
.admonition-title {
165+
background-color: #ffedcc;
166+
167+
&:before {
168+
color: #f0b37e;
169+
content: $icon-exclamation-circle;
170+
}
171+
}
172+
}
173+
174+
&.caution {
175+
border-color: #f0b37e;
176+
.admonition-title {
177+
background-color: #ffedcc;
178+
179+
&:before {
180+
color: #f0b37e;
181+
content: $icon-exclamation-triangle;
182+
}
183+
}
184+
}
185+
186+
&.warning {
187+
border-color: #f29f97;
188+
.admonition-title {
189+
background-color: #fdf3f2;
190+
191+
&:before {
192+
color: #f29f97;
193+
content: $icon-exclamation-triangle;
194+
}
195+
}
196+
}
197+
198+
&.danger {
199+
border-color: #f29f97;
200+
.admonition-title {
201+
background-color: #fdf3f2;
202+
203+
&:before {
204+
color: #f29f97;
205+
content: $icon-exclamation-triangle;
206+
}
207+
}
208+
}
209+
210+
&.error {
211+
border-color: #f29f97;
212+
.admonition-title {
213+
background-color: #fdf3f2;
214+
215+
&:before {
216+
color: #f29f97;
217+
content: $icon-times-circle;
218+
}
219+
}
220+
}
221+
222+
&.hint {
223+
border-color: #1abc9c;
224+
.admonition-title {
225+
background-color: #dbfaf4;
226+
227+
&:before {
228+
color: #1abc9c;
229+
content: $icon-lightbulb;
230+
}
231+
}
232+
}
233+
234+
&.tip {
235+
border-color: #1abc9c;
236+
.admonition-title {
237+
background-color: #dbfaf4;
238+
239+
&:before {
240+
color: #1abc9c;
241+
content: $icon-lightbulb;
242+
}
243+
}
244+
}
245+
246+
&.important {
247+
border-color: #6ab0de;
248+
.admonition-title {
249+
background-color: #e7f2fa;
250+
251+
&:before {
252+
color: #6ab0de;
253+
content: $icon-exclamation-circle;
254+
}
255+
}
256+
}
257+
258+
&.note {
259+
border-color: #6ab0de;
260+
.admonition-title {
261+
background-color: #e7f2fa;
262+
263+
&:before {
264+
color: #6ab0de;
265+
content: $icon-info-circle;
266+
}
267+
}
268+
}
269+
}

0 commit comments

Comments
 (0)