From 61027876fe83f8e268683121071bac407f7e6ab8 Mon Sep 17 00:00:00 2001 From: 12rambau Date: Sun, 5 Feb 2023 17:51:47 +0100 Subject: [PATCH 1/5] first draft of the admonition customization --- docs/_static/custom.css | 26 +++++ docs/conf.py | 1 + docs/user_guide/extending.rst | 198 ++++++++++++++++++++++++++++++++++ docs/user_guide/index.md | 1 + pyproject.toml | 1 + 5 files changed, 227 insertions(+) create mode 100644 docs/user_guide/extending.rst diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 416943ed3..ee7ef2768 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -17,3 +17,29 @@ background-color: var(--pst-color-success); opacity: 0.1; } + +/* custom css class to demonstrate admonition customization */ +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; +} + +div.admonition.admonition-icon > .admonition-title:after { + content: "\f24e"; +} + +div.admonition.admonition-youtube { + border-color: #ff0000; +} +div.admonition.admonition-youtube > .admonition-title:before { + background-color: #ff0000; +} +div.admonition.admonition-youtube > .admonition-title:after { + color: #ff0000; + content: "\f26c"; +} 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..6bb27e94a --- /dev/null +++ b/docs/user_guide/extending.rst @@ -0,0 +1,198 @@ +=================== +Extending the theme +=================== + +This theme can be extended using other sphinx extentions, their interaction with the pydata-sphinx-theme is described in this section. + +Customize admonitions +===================== + +Admonitions are based on the Sphinx admonition system described in :doc:`../examples/kitchen-sink/admonition`. They are fully customizable to render more complex configuration. + +collapsing +---------- + +To make the admonitions collapsable, we suggest to rely on the `sphinx-togglebutton `__ extention. Follow the instalation instruction from their documentation and add it to the ``extentions`` in your ``conf.py``: + +.. code-block:: python + + extentions = [ + # [...] + "sphinx_togglebutton" + ] + +Then add the ``dropdown`` class to any admonition directive: + +.. note:: + :class: dropdown + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. note:: + :class: dropdown + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +custom title +------------ + +By design, admonitions are using an automatic title to display next to the icon. By using the generic ``admonition`` directive, the first argument will be used as admonition title. +Default admonitions are rendered with your custom title, a :fas:`bell` icon and the "note" admonition coloring. + +.. admonition:: custom + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. admonition:: custom + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +You can also use one of the predifined color-icon by adding one of the existing admonition class to your custom admonition. This theme supports: + +- ``attention`` +- ``caution`` +- ``warning`` +- ``danger`` +- ``error`` +- ``hint`` +- ``tip`` +- ``important`` +- ``note`` +- ``seealso`` +- ``admonition-todo`` + +So to display the previous custom admonition with the "warning" styling, add the class ``warning`` to the directive: + +.. admonition:: custom + :class: warning + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. admonition:: custom + :class: warning + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +customize colors +---------------- + +If the available coloring are not fitting your requirements, create an extra css class in your ``custom.css`` file and update the colors of the admonition. Use the same color for both background and title the transparency is computed automatically by the theme. + +.. admonition:: custom + :class: admonition-olive + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. admonition:: custom + :class: admonition-olive + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + + .. tab-item:: css + + .. code-block:: css + + /* /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; + } + +customize icon +-------------- + +If the default :fas:`bell` icon not fitting your requirements, create an extra css class in your ``custom.css`` file and update the icon of the admonition. The theme support natively fontawesome V6 icons so go to their `website `__ and copy the unicode value of your custom icon and set it in your custom class: + +.. admonition:: custom + :class: admonition-icon + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. admonition:: custom + :class: admonition-icon + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + + .. tab-item:: css + + .. code-block:: css + + /* /custom.css */ + + div.admonition.admonition-icon > .admonition-title:after { + content: "\f24e" /* the fa-scale icon */ + } + +complete customization +---------------------- + +Combine all of the above to get a fully customized admonition: + +.. admonition:: youtube + :class: dropdown admonition-youtube + + .. youtube:: dQw4w9WgXcQ + +.. tab-set:: + + .. tab-item:: rst + + .. code-block:: rst + + .. admonition:: youtube + :class: dropdown admonition-youtube + + .. youtube:: dQw4w9WgXcQ + + .. tab-item:: css + + .. code-block:: css + + /* /custom.css */ + + div.admonition.admonition-youtube { + border-color: #FF0000; /* the youtube red */ + } + div.admonition.admonition-youtube > .admonition-title:before { + background-color: #FF0000; + } + div.admonition.admonition-youtube > .admonition-title:after { + color: #FF0000; + content: "\f26c"; /* fa-brands fa-tv */ + } 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 b100191fa..66ee3175d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,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", From 8b26bc806959e720ab70a9c9708dfceaa04ca4c5 Mon Sep 17 00:00:00 2001 From: 12rambau Date: Sun, 5 Feb 2023 18:55:46 +0100 Subject: [PATCH 2/5] typo in doc link --- docs/user_guide/extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst index 6bb27e94a..d1902c299 100644 --- a/docs/user_guide/extending.rst +++ b/docs/user_guide/extending.rst @@ -7,7 +7,7 @@ This theme can be extended using other sphinx extentions, their interaction with Customize admonitions ===================== -Admonitions are based on the Sphinx admonition system described in :doc:`../examples/kitchen-sink/admonition`. They are fully customizable to render more complex configuration. +Admonitions are based on the Sphinx admonition system described in :doc:`../examples/kitchen-sink/admonitions`. They are fully customizable to render more complex configuration. collapsing ---------- From 2f58e3bfbac8b07eaeebf76ea00a9bacfae424ce Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 7 Feb 2023 14:27:08 -0600 Subject: [PATCH 3/5] flesh out admon. customization example; DRY --- docs/_static/custom.css | 20 +++- docs/user_guide/extending.rst | 200 ++++++++++++++++------------------ 2 files changed, 111 insertions(+), 109 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index ee7ef2768..1813e094d 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -18,7 +18,12 @@ opacity: 0.1; } -/* custom css class to demonstrate admonition customization */ +/* 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; } @@ -28,18 +33,25 @@ div.admonition.admonition-olive > .admonition-title:before { 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"; + content: "\f24e"; /* the fa-scale icon */ } +/* end-custom-icon */ + +/* begin-custom-youtube/* /custom.css */ div.admonition.admonition-youtube { - border-color: #ff0000; + 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"; + content: "\f26c"; /* fa-brands fa-tv */ } +/* end-custom-youtube */ diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst index d1902c299..509b49ecb 100644 --- a/docs/user_guide/extending.rst +++ b/docs/user_guide/extending.rst @@ -2,197 +2,187 @@ Extending the theme =================== -This theme can be extended using other sphinx extentions, their interaction with the pydata-sphinx-theme is described in this section. +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. -Customize admonitions -===================== +Collapsible admonitions +======================= -Admonitions are based on the Sphinx admonition system described in :doc:`../examples/kitchen-sink/admonitions`. They are fully customizable to render more complex configuration. - -collapsing ----------- - -To make the admonitions collapsable, we suggest to rely on the `sphinx-togglebutton `__ extention. Follow the instalation instruction from their documentation and add it to the ``extentions`` in your ``conf.py``: +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-block:: python - extentions = [ + extensions = [ # [...] "sphinx_togglebutton" ] -Then add the ``dropdown`` class to any admonition directive: +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 - .. code-block:: rst + .. include:: ./extending.rst + :start-after: begin-example-dropdown + :end-before: .. end-example-dropdown + :literal: + :class: highlight-rst + - .. note:: - :class: dropdown +Custom admonition styles +======================== - Lorem ipsum dolor sit amet, consectetur adipiscing elit. +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. -custom title ------------- -By design, admonitions are using an automatic title to display next to the icon. By using the generic ``admonition`` directive, the first argument will be used as admonition title. -Default admonitions are rendered with your custom title, a :fas:`bell` icon and the "note" admonition coloring. +Customizing the title +--------------------- -.. admonition:: custom +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 - .. code-block:: rst + .. include:: ./extending.rst + :start-after: begin-example-title + :end-before: .. end-example-title + :literal: + :class: highlight-rst - .. admonition:: custom - Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Styling with semantic color names +--------------------------------- -You can also use one of the predifined color-icon by adding one of the existing admonition class to your custom admonition. This theme supports: +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): -- ``attention`` -- ``caution`` -- ``warning`` -- ``danger`` -- ``error`` -- ``hint`` -- ``tip`` -- ``important`` -- ``note`` -- ``seealso`` -- ``admonition-todo`` - -So to display the previous custom admonition with the "warning" styling, add the class ``warning`` to the directive: - -.. admonition:: custom +.. 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 - .. code-block:: rst + .. include:: ./extending.rst + :start-after: begin-example-semantic + :end-before: .. end-example-semantic + :literal: + :class: highlight-rst - .. admonition:: custom - :class: warning +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). - Lorem ipsum dolor sit amet, consectetur adipiscing elit. -customize colors ----------------- +Customizing the color +--------------------- -If the available coloring are not fitting your requirements, create an extra css class in your ``custom.css`` file and update the colors of the admonition. Use the same color for both background and title the transparency is computed automatically by the theme. +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: -.. admonition:: custom +.. 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 - .. code-block:: rst - - .. admonition:: custom - :class: admonition-olive - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. + .. include:: ./extending.rst + :start-after: begin-example-color + :end-before: .. end-example-color + :literal: + :class: highlight-rst .. tab-item:: css - .. code-block:: css - - /* /custom.css */ + .. include:: ../_static/custom.css + :start-after: begin-custom-color + :end-before: /* end-custom-color + :literal: + :class: highlight-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; - } -customize icon --------------- +Using a custom icon +------------------- -If the default :fas:`bell` icon not fitting your requirements, create an extra css class in your ``custom.css`` file and update the icon of the admonition. The theme support natively fontawesome V6 icons so go to their `website `__ and copy the unicode value of your custom icon and set it in your custom class: +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: -.. admonition:: custom +.. 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 - .. code-block:: rst - - .. admonition:: custom - :class: admonition-icon - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. + .. include:: ./extending.rst + :start-after: begin-example-icon + :end-before: .. end-example-icon + :literal: + :class: highlight-rst .. tab-item:: css - .. code-block:: css - - /* /custom.css */ + .. include:: ../_static/custom.css + :start-after: begin-custom-icon + :end-before: /* end-custom-icon + :literal: + :class: highlight-css - div.admonition.admonition-icon > .admonition-title:after { - content: "\f24e" /* the fa-scale icon */ - } -complete customization ----------------------- +Combining all three customizations +---------------------------------- -Combine all of the above to get a fully customized admonition: +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: -.. admonition:: youtube +.. begin-example-youtube +.. admonition:: YouTube :class: dropdown admonition-youtube .. youtube:: dQw4w9WgXcQ +.. end-example-youtube .. tab-set:: .. tab-item:: rst - .. code-block:: rst - - .. admonition:: youtube - :class: dropdown admonition-youtube - - .. youtube:: dQw4w9WgXcQ + .. include:: ./extending.rst + :start-after: begin-example-youtube + :end-before: .. end-example-youtube + :literal: + :class: highlight-rst .. tab-item:: css - .. code-block:: css - - /* /custom.css */ - - div.admonition.admonition-youtube { - border-color: #FF0000; /* the youtube red */ - } - div.admonition.admonition-youtube > .admonition-title:before { - background-color: #FF0000; - } - div.admonition.admonition-youtube > .admonition-title:after { - color: #FF0000; - content: "\f26c"; /* fa-brands fa-tv */ - } + .. include:: ../_static/custom.css + :start-after: begin-custom-youtube + :end-before: /* end-custom-youtube + :literal: + :class: highlight-css From 0a58f11157f458acd84ebb94b2c7cfb80848a25e Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 9 Feb 2023 13:37:16 -0600 Subject: [PATCH 4/5] use :code:rst instead of :literal: --- docs/user_guide/extending.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst index 509b49ecb..084790199 100644 --- a/docs/user_guide/extending.rst +++ b/docs/user_guide/extending.rst @@ -9,7 +9,7 @@ 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-block:: python +.. code:: python extensions = [ # [...] @@ -32,7 +32,7 @@ Then add the ``dropdown`` class to any admonition directive (shown here on a ``n .. include:: ./extending.rst :start-after: begin-example-dropdown :end-before: .. end-example-dropdown - :literal: + :code: rst :class: highlight-rst @@ -62,7 +62,7 @@ The title is specified on the same line as the ``.. admonition::`` directive: .. include:: ./extending.rst :start-after: begin-example-title :end-before: .. end-example-title - :literal: + :code: rst :class: highlight-rst @@ -87,7 +87,7 @@ Note that it updates both the color and the icon. .. include:: ./extending.rst :start-after: begin-example-semantic :end-before: .. end-example-semantic - :literal: + :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). @@ -114,7 +114,7 @@ Add the new class to your `custom.css Date: Sun, 12 Feb 2023 14:40:18 +0100 Subject: [PATCH 5/5] Update docs/_static/custom.css --- docs/_static/custom.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index 1813e094d..10feae3a2 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -52,6 +52,6 @@ div.admonition.admonition-youtube > .admonition-title:before { } div.admonition.admonition-youtube > .admonition-title:after { color: #ff0000; - content: "\f26c"; /* fa-brands fa-tv */ + content: "\f26c"; /* fa-solid fa-tv */ } /* end-custom-youtube */