mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
[docs] add icons to admonition titles (#12486)
and also replace ad-hoc "more" icon in quickstart, with using `seealso` admonition
This commit is contained in:
Chris Sewell
GitHub
parent
d130c2e710
commit
953c0097ef
BIN
doc/_static/more.png
vendored
BIN
doc/_static/more.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 KiB |
122
doc/_themes/sphinx13/static/sphinx13.css
vendored
122
doc/_themes/sphinx13/static/sphinx13.css
vendored
@ -4,13 +4,33 @@
|
||||
: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 */
|
||||
--color-admonition-bg: hsl(0, 0%, 90%);
|
||||
--color-admonition-fg: hsl(0, 0%, 50%);
|
||||
--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 {
|
||||
@ -392,15 +412,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;
|
||||
background-color: #dddddd;
|
||||
div.admonition > p.admonition-title {
|
||||
position: relative;
|
||||
font-weight: 500;
|
||||
background-color: var(--color-admonition-bg);
|
||||
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 {
|
||||
@ -417,10 +443,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(--color-admonition-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;
|
||||
@ -556,8 +651,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 {
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user