From 121873d8db8dd76de8948b64be692bfce75561a4 Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Mon, 13 Feb 2023 10:32:50 +0100 Subject: [PATCH] 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 --- docs/_static/custom.css | 38 +++++++ docs/conf.py | 1 + docs/user_guide/extending.rst | 188 ++++++++++++++++++++++++++++++++++ docs/user_guide/index.md | 1 + pyproject.toml | 1 + 5 files changed, 229 insertions(+) create mode 100644 docs/user_guide/extending.rst diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 416943ed3..10feae3a2 100644 --- a/docs/_static/custom.css +++ b/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/* /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/* /custom.css */ + +div.admonition.admonition-icon > .admonition-title:after { + content: "\f24e"; /* the fa-scale icon */ +} +/* end-custom-icon */ + +/* begin-custom-youtube/* /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 */ diff --git a/docs/conf.py b/docs/conf.py index 473c03a57..398fa920a 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst new file mode 100644 index 000000000..084790199 --- /dev/null +++ b/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 `__ 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 `__ 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 `__ (``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 `__ 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 `__ file. The theme supports `fontawesome v6 icons `__ ("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 diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 6a25c428f..886708237 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -54,6 +54,7 @@ keyboard-shortcuts theme-elements ablog web-components +extending ``` ```{toctree} diff --git a/pyproject.toml b/pyproject.toml index 2e33c4c8e..d6d78bcdd 100644 --- a/pyproject.toml +++ b/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",