From b82f61f7044665b900b0d8f556cbe207f3133837 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 20 Dec 2019 11:01:41 +0100 Subject: [PATCH] doc: reST primer -- describe admonitions & customize their CSS Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 73 +++++++++++++++++------------ docs/dev/reST.rst | 72 ++++++++++++++++++++++++++-- 2 files changed, 110 insertions(+), 35 deletions(-) diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 747cb0507..10cfc413e 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -28,53 +28,64 @@ p.sidebar-title, .sidebar p { list-style-type: disclosure-closed; } +/* admonitions +*/ -div.admonition, -div.topic { +div.admonition, div.topic { background-color: #fafafa; margin: 8px 0px; padding: 1em; - border: none; + border-radius: 3pt 0 0 3pt; + border-top: none; + border-right: none; + border-bottom: none; + border-left: 5pt solid #ccc; } +p.admonition-title:after { + content: none; +} + +.admonition.hint { border-color: #416dc0b0; } +.admonition.note { border-color: #6c856cb0; } +.admonition.tip { border-color: #85c5c2b0; } +.admonition.attention { border-color: #ecec97b0; } +.admonition.caution { border-color: #a6c677b0; } +.admonition.danger { border-color: #d46262b0; } +.admonition.important { border-color: #dfa3a3b0; } +.admonition.error { border-color: red; } +.admonition.warning { border-color: darkred; } + +.admonition.admonition-generic-admonition-title { + border-color: #416dc0b0; +} + + /* admonitions with (rendered) reST markup examples (:class: rst-example) * * .. admonition:: title of the example * :class: rst-example * .... -/* navigation menu: use sans font and select light/dark colors for better -* contrast. */ div.rst-example { - padding-left: 12px; - padding-right: 12px; - background-color: white; - transform: scale(0.9); - transition: transform 1s; + padding-left: 12px; + padding-right: 12px; + background-color: inherit; + transform: scale(0.9); + transition: transform 1s; + border-left: none; } -/* div.rst-example > .admonition-title { */ -/* background-color: inherit; */ -/* color: inherit; */ -/* } */ - -/* div.rst-example > .admonition-title:after{ */ -/* font-family: inherit; */ -/* font-style: italic; */ -/* content: " // hover mouse over .."; */ -/* } */ - @media screen { - div.rst-example:hover { - transform: scale(1); - background-color: inherit; - padding-left: inherit; - padding-right: inherit; - border-left: inherit; - } + div.rst-example:hover { + transform: scale(1); + padding-left: inherit; + padding-right: inherit; + border-left: inherit; + } - div.rst-example:hover > .admonition-title { - display: none; - } + div.rst-example:hover > .admonition-title { + display: none; + } } diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 5522f9e15..69e4a9305 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -16,8 +16,6 @@ generated and deployed at :docs:`github.io <.>`. The sources of Searx's documentation are located at :origin:`docs`. Run :ref:`make docs-live ` to build HTML while editing. ------- - .. sidebar:: Further reading - Sphinx-Primer_ @@ -36,8 +34,6 @@ The sources of Searx's documentation are located at :origin:`docs`. Run :local: :backlinks: entry ------- - Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_. @@ -593,6 +589,74 @@ Further list blocks - doctest blocks (:duref:`ref `) +Admonitions +=========== + +Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, +:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, , +:dudir:`warning` and the generic :dudir:`admonition `. + +.. code:: reST + + .. admonition:: generic admonition title + + lorem ipsum .. + + .. hint:: + + lorem ipsum .. + + .. note:: + + lorem ipsum .. + + .. warning:: + + lorem ipsum .. + + +.. admonition:: generic admonition title + + lorem ipsum .. + +.. hint:: + + lorem ipsum .. + +.. note:: + + lorem ipsum .. + +.. tip:: + + lorem ipsum .. + +.. attention:: + + lorem ipsum .. + +.. caution:: + + lorem ipsum .. + +.. danger:: + + lorem ipsum .. + +.. important:: + + lorem ipsum .. + +.. error:: + + lorem ipsum .. + +.. warning:: + + lorem ipsum .. + + + .. _KISS: https://en.wikipedia.org/wiki/KISS_principle .. _readability: https://docs.python-guide.org/writing/style/ .. _Sphinx-Primer: