Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOCS: admonition customization #1155

Merged
merged 5 commits into from
Feb 13, 2023
Merged

DOCS: admonition customization #1155

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6102787
first draft of the admonition customization
12rambau Feb 5, 2023
8b26bc8
typo in doc link
12rambau Feb 5, 2023
2f58e3b
flesh out admon. customization example; DRY
drammock Feb 7, 2023
0a58f11
use :code:rst instead of :literal:
drammock Feb 9, 2023
a3e64ab
Update docs/_static/custom.css
12rambau Feb 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/_static/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-brands fa-tv */
12rambau marked this conversation as resolved.
Show resolved Hide resolved
}
/* end-custom-youtube */
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
188 changes: 188 additions & 0 deletions docs/user_guide/extending.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually created a tiny little sphinx extension to show off syntax examples, maybe it would be useful here?

https://ebp-sphinx-examples.readthedocs.io/en/latest/

It gives you an example directive like:

```{example}
**foo**
```

And it create a little preview + the raw syntax to show how to make the preview.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that would be perfect but you can't display 2 files yet right (like in these examples css + rst) ?

I will merge it and we'll see how to use it in the upcoming future

.. 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
1 change: 1 addition & 0 deletions docs/user_guide/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ keyboard-shortcuts
theme-elements
ablog
web-components
extending
```

```{toctree}
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down