[docs] add icons for admonitions

and also replace ad-hoc "more" icon in quickstart, with using `seealso` admonition
sphinx-doc · Jun 27, 2024 · 2bb24e1 · 2bb24e1
1 parent ad6f659
commit 2bb24e1
Show file tree

Hide file tree

Showing 3 changed files with 138 additions and 28 deletions.
diff --git a/doc/_static/more.png b/doc/_static/more.png
diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css
@@ -4,13 +4,31 @@
 :root {
     --fonts-sans-serif: system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
     --colour-sphinx-blue: #0A507A;
-    --colour-warning-bg: #f8e3d0;
-    --colour-note-bg: #dce7fc;
-    --colour-success-bg: #d6ece1;
-    --colour-todo-bg: #e0c7ff;
     --colour-text: #333;
     --colour-links-light: #057;
     --admonition-radius: 3px;
+
+    /* colours for admonition titles */
+    --colour-warning-bg: hsl(28.5, 74%, 90%);
+    --colour-warning-fg: hsl(28.5, 74%, 50%);
+    --colour-note-bg: hsl(219.5, 84%, 90%);
+    --colour-note-fg: hsl(219.5, 84%, 50%);
+    --colour-success-bg: hsl(150, 36.7%, 90%);
+    --colour-success-fg: hsl(150, 36.7%, 50%);
+    --colour-error-bg: hsl(0, 37%, 90%);
+    --colour-error-fg: hsl(0, 37%, 50%);
+    --colour-todo-bg: hsl(266.8, 100%, 90%);
+    --colour-todo-fg: hsl(266.8, 100%, 50%);
+
+    /* icons used for admonition titles */
+    --icon-pencil: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>');
+    --icon-abstract: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 5h16v2H4V5m0 4h16v2H4V9m0 4h16v2H4v-2m0 4h10v2H4v-2z"/></svg>');
+    --icon-info: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 9h-2V7h2m0 10h-2v-6h2m-1-9A10 10 0 002 12a10 10 0 0010 10 10 10 0 0010-10A10 10 0 0012 2z"/></svg>');
+    --icon-flame: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.55 11.2c-.23-.3-.5-.56-.76-.82-.65-.6-1.4-1.03-2.03-1.66C13.3 7.26 13 4.85 13.91 3c-.91.23-1.75.75-2.45 1.32-2.54 2.08-3.54 5.75-2.34 8.9.04.1.08.2.08.33 0 .22-.15.42-.35.5-.22.1-.46.04-.64-.12a.83.83 0 01-.15-.17c-1.1-1.43-1.28-3.48-.53-5.12C5.89 10 5 12.3 5.14 14.47c.04.5.1 1 .27 1.5.14.6.4 1.2.72 1.73 1.04 1.73 2.87 2.97 4.84 3.22 2.1.27 4.35-.12 5.96-1.6 1.8-1.66 2.45-4.32 1.5-6.6l-.13-.26c-.2-.46-.47-.87-.8-1.25l.05-.01m-3.1 6.3c-.28.24-.73.5-1.08.6-1.1.4-2.2-.16-2.87-.82 1.19-.28 1.89-1.16 2.09-2.05.17-.8-.14-1.46-.27-2.23-.12-.74-.1-1.37.18-2.06.17.38.37.76.6 1.06.76 1 1.95 1.44 2.2 2.8.04.14.06.28.06.43.03.82-.32 1.72-.92 2.27h.01z"/></svg>');
+    --icon-question: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.07 11.25l-.9.92C13.45 12.89 13 13.5 13 15h-2v-.5c0-1.11.45-2.11 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41a2 2 0 00-2-2 2 2 0 00-2 2H8a4 4 0 014-4 4 4 0 014 4 3.2 3.2 0 01-.93 2.25M13 19h-2v-2h2M12 2A10 10 0 002 12a10 10 0 0010 10 10 10 0 0010-10c0-5.53-4.5-10-10-10z"/></svg>');
+    --icon-warning: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 14h-2v-4h2m0 8h-2v-2h2M1 21h22L12 2 1 21z"/></svg>');
+    --icon-failure: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2c5.53 0 10 4.47 10 10s-4.47 10-10 10S2 17.53 2 12 6.47 2 12 2m3.59 5L12 10.59 8.41 7 7 8.41 10.59 12 7 15.59 8.41 17 12 13.41 15.59 17 17 15.59 13.41 12 17 8.41 15.59 7z"/></svg>');
+    --icon-spark: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11.5 20l4.86-9.73H13V4l-5 9.73h3.5V20M12 2c2.75 0 5.1 1 7.05 2.95C21 6.9 22 9.25 22 12s-1 5.1-2.95 7.05C17.1 21 14.75 22 12 22s-5.1-1-7.05-2.95C3 17.1 2 14.75 2 12s1-5.1 2.95-7.05C6.9 3 9.25 2 12 2z"/></svg>');
 }
 
 body {
@@ -388,15 +406,21 @@ div.admonition > pre, div.warning > pre {
     margin: 0.4em 1em 0.4em 1em;
 }
 
-div.admonition > p.admonition-title,
-div.warning > p.admonition-title {
-    font-weight: bold;
+div.admonition > p.admonition-title {
+    position: relative;
+    font-weight: 500;
     background-color: #dddddd;
     margin: -1rem -1rem 0.8rem -1rem;
-    padding: 0.3rem 1rem;
+    padding: 0.3rem 1rem 0.3rem 2rem;
     border-radius: var(--admonition-radius) var(--admonition-radius) 0 0;
 }
 
+div.attention > p.admonition-title,
+div.danger > p.admonition-title,
+div.error > p.admonition-title {
+    background-color: var(--colour-error-bg);
+}
+
 div.important > p.admonition-title,
 div.caution > p.admonition-title,
 div.warning > p.admonition-title {
@@ -413,10 +437,79 @@ div.seealso > p.admonition-title {
     background-color: var(--colour-success-bg);
 }
 
-div.todo > p.admonition-title {
+div.admonition-todo > p.admonition-title {
     background-color: var(--colour-todo-bg);
 }
 
+p.admonition-title::before {
+    content: "";
+    height: 1rem;
+    left: .5rem;
+    position: absolute;
+    width: 1rem;
+    background-color: #5f5f5f;
+}
+
+div.admonition > p.admonition-title::before {
+    background-color: var(--colour-error-fg);
+    -webkit-mask-image: var(--icon-abstract);
+    mask-image: var(--icon-abstract);
+}
+div.attention > p.admonition-title::before {
+    background-color: var(--colour-error-fg);
+    -webkit-mask-image: var(--icon-warning);
+    mask-image: var(--icon-warning);
+}
+div.caution > p.admonition-title::before {
+    background-color: var(--colour-warning-fg);
+    -webkit-mask-image: var(--icon-spark);
+    mask-image: var(--icon-spark);
+}
+div.danger > p.admonition-title::before {
+    background-color: var(--colour-error-fg);
+    -webkit-mask-image: var(--icon-spark);
+    mask-image: var(--icon-spark);
+}
+div.error > p.admonition-title::before {
+    background-color: var(--colour-error-fg);
+    -webkit-mask-image: var(--icon-failure);
+    mask-image: var(--icon-failure);
+}
+div.hint > p.admonition-title::before {
+    background-color: var(--colour-success-fg);
+    -webkit-mask-image: var(--icon-question);
+    mask-image: var(--icon-question);
+}
+div.important > p.admonition-title::before {
+    background-color: var(--colour-warning-fg);
+    -webkit-mask-image: var(--icon-flame);
+    mask-image: var(--icon-flame);
+}
+div.note > p.admonition-title::before {
+    background-color: var(--colour-note-fg);
+    -webkit-mask-image: var(--icon-pencil);
+    mask-image: var(--icon-pencil);
+}
+div.seealso > p.admonition-title::before {
+    background-color: var(--colour-success-fg);
+    -webkit-mask-image: var(--icon-info);
+    mask-image: var(--icon-info);
+}
+div.tip > p.admonition-title::before {
+    background-color: var(--colour-success-fg);
+    -webkit-mask-image: var(--icon-info);
+    mask-image: var(--icon-info);
+}
+div.admonition-todo > p.admonition-title::before {
+    background-color: var(--colour-todo-fg);
+    -webkit-mask-image: var(--icon-pencil);
+    mask-image: var(--icon-pencil);
+}
+div.warning > p.admonition-title::before {
+    background-color: var(--colour-warning-fg);
+    -webkit-mask-image: var(--icon-warning);
+    mask-image: var(--icon-warning);
+}
 
 div.warning {
     border: 1px solid #940000;
@@ -552,8 +645,13 @@ then for larger screens align them two per-row. */
 .sphinx-feature p {
     hyphens: none !important;
 }
-.sphinx-feature > p.admonition-title {
+div.sphinx-feature > p.admonition-title {
     background-color: #f7f7f7 !important;
+    padding-left: 1rem;
+    font-weight: bold;
+}
+div.sphinx-feature > p.admonition-title::before {
+    display: none;
 }
 @media (min-width: 768px) {
     .sphinx-feature {

diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
@@ -54,7 +54,8 @@ to contain the root of the "table of contents tree" (or *toctree*).  This is one
 of the main things that Sphinx adds to reStructuredText, a way to connect
 multiple files to a single hierarchy of documents.
 
-.. sidebar:: reStructuredText directives
+.. admonition:: reStructuredText directives
+   :class: note
 
    ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece
    of markup.  Directives can have arguments, options and content.
@@ -95,7 +96,9 @@ documents to include are given as :term:`document name`\ s, which in short
 means that you leave off the file name extension and use forward slashes
 (``/``) as directory separators.
 
-|more| Read more about :ref:`the toctree directive <toctree-directive>`.
+.. seealso::
+
+   Read more about :ref:`the toctree directive <toctree-directive>`.
 
 You can now create the files you listed in the ``toctree`` and add content, and
 their section titles will be inserted (up to the ``maxdepth`` level) at the
@@ -118,8 +121,11 @@ for this document -- use the "Show Source" link in the sidebar.
 
 .. todo:: Update the below link when we add new guides on these.
 
-|more| See :doc:`/usage/restructuredtext/index` for a more in-depth
-introduction to reStructuredText, including markup added by Sphinx.
+.. seealso::
+
+   :doc:`/usage/restructuredtext/index`
+   for a more in-depth introduction to reStructuredText,
+   including markup added by Sphinx.
 
 
 Running the build
@@ -137,8 +143,10 @@ directory in which you want to place the built documentation.
 The :option:`-M <sphinx-build -M>` option selects a builder; in this example
 Sphinx will build HTML files.
 
-|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all
-options that :program:`sphinx-build` supports.
+.. seealso::
+
+   Refer to the :doc:`sphinx-build man page </man/sphinx-build>`
+   for all options that :program:`sphinx-build` supports.
 
 However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
 :file:`make.bat` which make life even easier for you. These can be executed by
@@ -220,8 +228,10 @@ Each domain will have special rules for how the signatures can look like, and
 make the formatted output look pretty, or add specific features like links to
 parameter types, e.g. in the C/C++ domains.
 
-|more| See :doc:`/usage/domains/index` for all the available domains
-and their directives/roles.
+.. seealso::
+
+   :doc:`/usage/domains/index`
+   for all the available domains and their directives/roles.
 
 
 Basic configuration
@@ -245,8 +255,10 @@ Keep in mind that the file uses Python syntax for strings, numbers, lists and
 so on.  The file is saved in UTF-8 by default, as indicated by the encoding
 declaration in the first line.
 
-|more| See :doc:`/usage/configuration` for documentation of all available
-config values.
+.. seealso::
+
+   :doc:`/usage/configuration`
+   for documentation of all available config values.
 
 
 .. todo:: Move this entire doc to a different section
@@ -259,8 +271,10 @@ source files, in documentation strings.  Sphinx supports the inclusion of
 docstrings from your modules with an :dfn:`extension` (an extension is a Python
 module that provides additional features for Sphinx projects) called *autodoc*.
 
-|more| See :mod:`sphinx.ext.autodoc` for the complete description of the
-features of autodoc.
+.. seealso::
+
+   :mod:`sphinx.ext.autodoc`
+   for the complete description of the features of autodoc.
 
 Intersphinx
 -----------
@@ -288,8 +302,10 @@ download the list of valid targets).  Intersphinx also works for some other
 :term:`domain`\'s roles including ``:ref:``, however it doesn't work for
 ``:doc:`` as that is non-domain role.
 
-|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the
-features of intersphinx.
+.. seealso::
+
+   :mod:`sphinx.ext.intersphinx`
+   for the complete description of the features of intersphinx.
 
 
 More topics to be covered
@@ -308,7 +324,3 @@ More topics to be covered
 .. [#] This is the usual layout.  However, :file:`conf.py` can also live in
        another directory, the :term:`configuration directory`.  Refer to the
        :doc:`sphinx-build man page </man/sphinx-build>` for more information.
-
-.. |more| image:: /_static/more.png
-          :align: middle
-          :alt: more info