From 2bb24e182d8b45edb70eb900c6eaab08a879f946 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Thu, 27 Jun 2024 22:23:22 +0200 Subject: [PATCH 1/2] [docs] add icons for admonitions and also replace ad-hoc "more" icon in quickstart, with using `seealso` admonition --- doc/_static/more.png | Bin 1351 -> 0 bytes doc/_themes/sphinx13/static/sphinx13.css | 118 +++++++++++++++++++++-- doc/usage/quickstart.rst | 48 +++++---- 3 files changed, 138 insertions(+), 28 deletions(-) delete mode 100644 doc/_static/more.png diff --git a/doc/_static/more.png b/doc/_static/more.png deleted file mode 100644 index 97553a8b7e0543b2f7887c51f2d854c0b6e4e956..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1351 zcmV-N1-SZ&P)R3GWh^dTYCz%+x z-wkjkVN%vC>9D!$QW@v}k%bi~!-f{Q0_n-4_;E{)kCnLXM>4T${}^CofN{e{ zTc`>#(Q#P2@>H+W;d*=RbIuF)ssYN%LtMA+dFNZ}UvL%Ev6F;tM57Ii*e=(==44p6 z;xtc`JNiC)=bqsjFvSmM92FT!qh2{=?%FLISDriWj3cj%x?uIq;G9F>3?q=xr8FVL zyKwZf&EA-(xQocd+w{GCum((F2L*T}&YSwhmX#MLp1k7fsA=g-SloydK+@15*P$U; z2rx!}+&C&Ch{B$qQRw>-3+FEOrX;1UqDT5%L=DD(E>2U8oW&E4KJU!KuXU%!j4?{= z*E$f=d{9LQ8dNaLMuv>%KD8CK!QGfOZH^}^W7K@c@h`=UMg(kq_D8}qizXj2X4%A5 z5|z~~vpN0dG2#qH`Tc4;On7YxkYxoe&CLpc4?aFO*f}5r<-iRepA&ol7T9|0JL7oy@Hv}ZJ!*^5Qx2OU z!32X#ih{%graSp$Wz4d$c13wXG%icI&(TE`Qq_Lf}UL1)NEL>EiXl0tD0!q`RiW->Kri z9e?y_nzo9>e*$4p2Drqg#Cy|NNb?(+$J#ScQk$)Qx%Jh0(%MWx|3nz;pL2_bKoMGk zWyo~TLVHWMwmo}mm(axF^xl6%`%fq^)^4{$CIb?;!yoeDtN-2zk@zB0+=O0!niE63 zxxQT`@m3OFY!M$^1%wcZ3iDHN6;9^G&XPa<0_xoqv<7>CA_AzYtX7K33iS#tqxUL@ z^=rr(vfF%(;iaXayuN@uq1QpmFUk#(cqxg`GsTBxz!}h9X>G5N85m>{f*kTGa*x)| z7~@2VXfp{yb!}C4TbZ`>lk-BY;paLzkqxN@ZdrU#Ta|NOX8MFhA?8Dz)7@5?-{t_I zlZB~+X^Qwf?<4h`l5ey?__;90gDA*@(2wS|4n%-iuAw^zz|VQiaqQTIv)@cfn&_#n z&F#wlW!E`xU#)x<7B`6z$&k7mp_=2f2WmPk=bB+8(m=Re++<=JY$rSrcgDCG^KX-E z4tws_pWb=@s-A0_s-Wo4BdcH)w+i+~($-7^X6BM~OF4_$I&#^h<;yRRn&^!(W=9Is zPK>5c=q!`24!o>IYB!<-y`V+ulkUotSj^^+{t=r`tFHnHUNml`u7v z);JL~Wrf*--r8W2ndf#7<7qQ&j)ZYGw`7OZUabWy{s;zSf1fj8ZI7b&zqeJudJ&I2 zS_cpVTm>rWseLX(s~J<+DsDN7UQB4ct^WZT=*JlLWIzlu;QunitBlmD&Y=JR002ov JPDHLkV1jI?qNxA? diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index ec1642d2c80..9efc1de6c5a 100644 --- 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,'); + --icon-abstract: url('data:image/svg+xml;charset=utf-8,'); + --icon-info: url('data:image/svg+xml;charset=utf-8,'); + --icon-flame: url('data:image/svg+xml;charset=utf-8,'); + --icon-question: url('data:image/svg+xml;charset=utf-8,'); + --icon-warning: url('data:image/svg+xml;charset=utf-8,'); + --icon-failure: url('data:image/svg+xml;charset=utf-8,'); + --icon-spark: url('data:image/svg+xml;charset=utf-8,'); } 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 index 2f89b65b169..774a581a0cf 100644 --- 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 `. +.. seealso:: + + Read more about :ref:`the 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 ` option selects a builder; in this example Sphinx will build HTML files. -|more| Refer to the :doc:`sphinx-build man page ` for all -options that :program:`sphinx-build` supports. +.. seealso:: + + Refer to the :doc:`sphinx-build man page ` + 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 ` for more information. - -.. |more| image:: /_static/more.png - :align: middle - :alt: more info From 87fe8abeca6f9a1aba9ade77e01810e1fb7f5d78 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Thu, 27 Jun 2024 22:37:28 +0200 Subject: [PATCH 2/2] Update sphinx13.css --- doc/_themes/sphinx13/static/sphinx13.css | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 9efc1de6c5a..0bd52035af0 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -9,6 +9,8 @@ --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%); @@ -409,7 +411,7 @@ div.admonition > pre, div.warning > pre { div.admonition > p.admonition-title { position: relative; font-weight: 500; - background-color: #dddddd; + background-color: var(--color-admonition-bg); margin: -1rem -1rem 0.8rem -1rem; padding: 0.3rem 1rem 0.3rem 2rem; border-radius: var(--admonition-radius) var(--admonition-radius) 0 0; @@ -451,7 +453,7 @@ p.admonition-title::before { } div.admonition > p.admonition-title::before { - background-color: var(--colour-error-fg); + background-color: var(--color-admonition-fg); -webkit-mask-image: var(--icon-abstract); mask-image: var(--icon-abstract); }