Skip to content

Commit 121873d

Browse files
12rambaudrammock
12rambau
and
drammock
authored
DOCS: admonition customization (#1155)
* first draft of the admonition customization * typo in doc link * flesh out admon. customization example; DRY * use :code:rst instead of :literal: * Update docs/_static/custom.css --------- Co-authored-by: Daniel McCloy <[email protected]>
1 parent 7251a57 commit 121873d

File tree

5 files changed

+229
-0
lines changed

5 files changed

+229
-0
lines changed

‎docs/_static/custom.css

+38
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,41 @@
1717
background-color: var(--pst-color-success);
1818
opacity: 0.1;
1919
}
20+
21+
/* custom CSS classes (used in docs/user_guide/extending.rst) NOTE: the begin
22+
* and end markers are necessary for partial file includes! don't remove them.
23+
*/
24+
25+
/* begin-custom-color/* <your static path>/custom.css */
26+
27+
div.admonition.admonition-olive {
28+
border-color: olive;
29+
}
30+
div.admonition.admonition-olive > .admonition-title:before {
31+
background-color: olive;
32+
}
33+
div.admonition.admonition-olive > .admonition-title:after {
34+
color: olive;
35+
}
36+
/* end-custom-color */
37+
38+
/* begin-custom-icon/* <your static path>/custom.css */
39+
40+
div.admonition.admonition-icon > .admonition-title:after {
41+
content: "\f24e"; /* the fa-scale icon */
42+
}
43+
/* end-custom-icon */
44+
45+
/* begin-custom-youtube/* <your static path>/custom.css */
46+
47+
div.admonition.admonition-youtube {
48+
border-color: #ff0000; /* YouTube red */
49+
}
50+
div.admonition.admonition-youtube > .admonition-title:before {
51+
background-color: #ff0000;
52+
}
53+
div.admonition.admonition-youtube > .admonition-title:after {
54+
color: #ff0000;
55+
content: "\f26c"; /* fa-solid fa-tv */
56+
}
57+
/* end-custom-youtube */

‎docs/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
"jupyter_sphinx",
3030
"matplotlib.sphinxext.plot_directive",
3131
"myst_nb",
32+
"sphinxcontrib.youtube",
3233
# "nbsphinx", # Uncomment and comment-out MyST-NB for local testing purposes.
3334
"numpydoc",
3435
"sphinx_togglebutton",

‎docs/user_guide/extending.rst

+188
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
===================
2+
Extending the theme
3+
===================
4+
5+
There are many extensions available for Sphinx that can enhance your site or provide powerful customization abilities. Here we describe a few customizations that are popular with ``pydata-sphinx-theme`` users.
6+
7+
Collapsible admonitions
8+
=======================
9+
10+
The `sphinx-togglebutton <https://sphinx-togglebutton.readthedocs.io/en/latest/>`__ extension provides optional show/hide behavior for admonitions. Follow their installation instructions, then add it to the ``extentions`` list in your ``conf.py``:
11+
12+
.. code:: python
13+
14+
extensions = [
15+
# [...]
16+
"sphinx_togglebutton"
17+
]
18+
19+
Then add the ``dropdown`` class to any admonition directive (shown here on a ``note`` admonition):
20+
21+
.. begin-example-dropdown
22+
.. note::
23+
:class: dropdown
24+
25+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
26+
.. end-example-dropdown
27+
28+
.. tab-set::
29+
30+
.. tab-item:: rst
31+
32+
.. include:: ./extending.rst
33+
:start-after: begin-example-dropdown
34+
:end-before: .. end-example-dropdown
35+
:code: rst
36+
:class: highlight-rst
37+
38+
39+
Custom admonition styles
40+
========================
41+
42+
A `limited set <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ of admonitions are built-in to docutils (the rST → HTML engine that underlies Sphinx). However, it is possible to create custom admonitions with their own default colors, icons, and titles.
43+
44+
45+
Customizing the title
46+
---------------------
47+
48+
Although most admonitions have a default title like ``note`` or ``warning``, a generic ``admonition`` directive is built-in to docutils/Sphinx. In this theme, its color defaults to the same color as ``note`` admonitions, and it has a bell icon:
49+
50+
.. begin-example-title
51+
.. admonition:: Custom title!
52+
53+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
54+
.. end-example-title
55+
56+
The title is specified on the same line as the ``.. admonition::`` directive:
57+
58+
.. tab-set::
59+
60+
.. tab-item:: rst
61+
62+
.. include:: ./extending.rst
63+
:start-after: begin-example-title
64+
:end-before: .. end-example-title
65+
:code: rst
66+
:class: highlight-rst
67+
68+
69+
Styling with semantic color names
70+
---------------------------------
71+
72+
You can re-style any admonition to match any of the built-in admonition types using any of the semantic color names as a class (this is most useful for custom-titled admonitions):
73+
74+
.. begin-example-semantic
75+
.. admonition:: Custom title with "warning" style
76+
:class: warning
77+
78+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
79+
.. end-example-semantic
80+
81+
Note that it updates both the color and the icon.
82+
83+
.. tab-set::
84+
85+
.. tab-item:: rst
86+
87+
.. include:: ./extending.rst
88+
:start-after: begin-example-semantic
89+
:end-before: .. end-example-semantic
90+
:code: rst
91+
:class: highlight-rst
92+
93+
This theme defines classes for `the standard docutils admonition types <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ (``attention``, ``caution``, etc) and additionally supports ``seealso`` and ``todo`` admonitions (see :doc:`../examples/kitchen-sink/admonitions` for a demo of all built-in admonition styles).
94+
95+
96+
Customizing the color
97+
---------------------
98+
99+
Besides the pre-defined semantic color classes (see previous section) you can also add a bespoke color to any admonition by defining your own CSS class. Example:
100+
101+
.. begin-example-color
102+
.. admonition:: Admonition with custom "olive" color
103+
:class: admonition-olive
104+
105+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
106+
.. end-example-color
107+
108+
Add the new class to your `custom.css <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files>`__ file. As in the example below, be sure to use the same color for ``border-color``, ``background-color``, and ``color`` (the transparency effect is handled automatically by the theme).
109+
110+
.. tab-set::
111+
112+
.. tab-item:: rst
113+
114+
.. include:: ./extending.rst
115+
:start-after: begin-example-color
116+
:end-before: .. end-example-color
117+
:code: rst
118+
:class: highlight-rst
119+
120+
.. tab-item:: css
121+
122+
.. include:: ../_static/custom.css
123+
:start-after: begin-custom-color
124+
:end-before: /* end-custom-color
125+
:code: css
126+
:class: highlight-css
127+
128+
129+
Using a custom icon
130+
-------------------
131+
132+
Customizing the icon uses a similar process to customizing the color: create a new CSS class in your `custom.css <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files>`__ file. The theme supports `fontawesome v6 icons <https://fontawesome.com/v6/search?o=r&m=free&f=brands>`__ ("free" and "brands" sets). To use an icon, copy its unicode value into your custom class as shown in the CSS tab below:
133+
134+
.. begin-example-icon
135+
.. admonition:: Check out my custom icon
136+
:class: admonition-icon
137+
138+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
139+
.. end-example-icon
140+
141+
.. tab-set::
142+
143+
.. tab-item:: rst
144+
145+
.. include:: ./extending.rst
146+
:start-after: begin-example-icon
147+
:end-before: .. end-example-icon
148+
:code: rst
149+
:class: highlight-rst
150+
151+
.. tab-item:: css
152+
153+
.. include:: ../_static/custom.css
154+
:start-after: begin-custom-icon
155+
:end-before: /* end-custom-icon
156+
:code: css
157+
:class: highlight-css
158+
159+
160+
Combining all three customizations
161+
----------------------------------
162+
163+
Here we demonstrate an admonition with a custom icon, color, and title (and also make it collapsible). Note that the multiple admonition class names are space-separated:
164+
165+
.. begin-example-youtube
166+
.. admonition:: YouTube
167+
:class: dropdown admonition-youtube
168+
169+
.. youtube:: dQw4w9WgXcQ
170+
.. end-example-youtube
171+
172+
.. tab-set::
173+
174+
.. tab-item:: rst
175+
176+
.. include:: ./extending.rst
177+
:start-after: begin-example-youtube
178+
:end-before: .. end-example-youtube
179+
:code: rst
180+
:class: highlight-rst
181+
182+
.. tab-item:: css
183+
184+
.. include:: ../_static/custom.css
185+
:start-after: begin-custom-youtube
186+
:end-before: /* end-custom-youtube
187+
:code: css
188+
:class: highlight-css

‎docs/user_guide/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ keyboard-shortcuts
5454
theme-elements
5555
ablog
5656
web-components
57+
extending
5758
```
5859

5960
```{toctree}

‎pyproject.toml

+1
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ doc = [
6666
"sphinx-copybutton",
6767
"sphinx-design",
6868
"sphinx-togglebutton",
69+
"sphinxcontrib-youtube",
6970
# Install nbsphinx in case we want to test it locally even though we can't load
7071
# it at the same time as MyST-NB.
7172
"nbsphinx",

0 commit comments

Comments
 (0)