-
Notifications
You must be signed in to change notification settings - Fork 317
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
Showing
5 changed files
with
229 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
.. 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -54,6 +54,7 @@ keyboard-shortcuts | |
theme-elements | ||
ablog | ||
web-components | ||
extending | ||
``` | ||
|
||
```{toctree} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters