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 <dan@mccloy.info>

docs/_static/custom.css

@@ -17,3 +17,41 @@
   background-color: var(--pst-color-success);
   opacity: 0.1;
 }
+
+/* custom CSS classes (used in docs/user_guide/extending.rst) NOTE: the begin
+ *  and end markers are necessary for partial file includes! don't remove them.
+ */
+
+/* begin-custom-color/* <your static path>/custom.css */
+
+div.admonition.admonition-olive {
+  border-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:before {
+  background-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:after {
+  color: olive;
+}
+/* end-custom-color */
+
+/* begin-custom-icon/* <your static path>/custom.css */
+
+div.admonition.admonition-icon > .admonition-title:after {
+  content: "\f24e"; /* the fa-scale icon */
+}
+/* end-custom-icon */
+
+/* begin-custom-youtube/* <your static path>/custom.css */
+
+div.admonition.admonition-youtube {
+  border-color: #ff0000; /* YouTube red */
+}
+div.admonition.admonition-youtube > .admonition-title:before {
+  background-color: #ff0000;
+}
+div.admonition.admonition-youtube > .admonition-title:after {
+  color: #ff0000;
+  content: "\f26c"; /* fa-solid fa-tv */
+}
+/* end-custom-youtube */

docs/conf.py

@@ -29,6 +29,7 @@
     "jupyter_sphinx",
     "matplotlib.sphinxext.plot_directive",
     "myst_nb",
+    "sphinxcontrib.youtube",
     # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
     "numpydoc",
     "sphinx_togglebutton",

docs/user_guide/extending.rst

@@ -0,0 +1,188 @@
+===================
+Extending the theme
+===================
+
+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.
+
+Collapsible admonitions
+=======================
+
+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``:
+
+.. code:: python
+
+    extensions = [
+        # [...]
+        "sphinx_togglebutton"
+    ]
+
+Then add the ``dropdown`` class to any admonition directive (shown here on a ``note`` admonition):
+
+.. begin-example-dropdown
+.. note::
+    :class: dropdown
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+.. end-example-dropdown
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-dropdown
+            :end-before: .. end-example-dropdown
+            :code: rst
+            :class: highlight-rst
+
+
+Custom admonition styles
+========================
+
+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.
+
+
+Customizing the title
+---------------------
+
+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:
+
+.. begin-example-title
+.. admonition:: Custom title!
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+.. end-example-title
+
+The title is specified on the same line as the ``.. admonition::`` directive:
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-title
+            :end-before: .. end-example-title
+            :code: rst
+            :class: highlight-rst
+
+
+Styling with semantic color names
+---------------------------------
+
+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):
+
+.. begin-example-semantic
+.. admonition:: Custom title with "warning" style
+    :class: warning
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+.. end-example-semantic
+
+Note that it updates both the color and the icon.
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-semantic
+            :end-before: .. end-example-semantic
+            :code: rst
+            :class: highlight-rst
+
+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).
+
+
+Customizing the color
+---------------------
+
+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:
+
+.. begin-example-color
+.. admonition:: Admonition with custom "olive" color
+    :class: admonition-olive
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+.. end-example-color
+
+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).
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-color
+            :end-before: .. end-example-color
+            :code: rst
+            :class: highlight-rst
+
+    .. tab-item:: css
+
+        .. include:: ../_static/custom.css
+            :start-after: begin-custom-color
+            :end-before: /* end-custom-color
+            :code: css
+            :class: highlight-css
+
+
+Using a custom icon
+-------------------
+
+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:
+
+.. begin-example-icon
+.. admonition:: Check out my custom icon
+    :class: admonition-icon
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+.. end-example-icon
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-icon
+            :end-before: .. end-example-icon
+            :code: rst
+            :class: highlight-rst
+
+    .. tab-item:: css
+
+        .. include:: ../_static/custom.css
+            :start-after: begin-custom-icon
+            :end-before: /* end-custom-icon
+            :code: css
+            :class: highlight-css
+
+
+Combining all three customizations
+----------------------------------
+
+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:
+
+.. begin-example-youtube
+.. admonition:: YouTube
+    :class: dropdown admonition-youtube
+
+    ..  youtube:: dQw4w9WgXcQ
+.. end-example-youtube
+
+.. tab-set::
+
+    .. tab-item:: rst
+
+        .. include:: ./extending.rst
+            :start-after: begin-example-youtube
+            :end-before: .. end-example-youtube
+            :code: rst
+            :class: highlight-rst
+
+    .. tab-item:: css
+
+        .. include:: ../_static/custom.css
+            :start-after: begin-custom-youtube
+            :end-before: /* end-custom-youtube
+            :code: css
+            :class: highlight-css

docs/user_guide/index.md

@@ -54,6 +54,7 @@ keyboard-shortcuts
 theme-elements
 ablog
 web-components
+extending
 ```
 
 ```{toctree}

pyproject.toml

@@ -66,6 +66,7 @@ doc = [
   "sphinx-copybutton",
   "sphinx-design",
   "sphinx-togglebutton",
+  "sphinxcontrib-youtube",
   # Install nbsphinx in case we want to test it locally even though we can't load
   # it at the same time as MyST-NB.
   "nbsphinx",