doc: reST primer -- describe admonitions & customize their CSS

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-20 11:01:41 +01:00
parent e1566e68aa
commit b82f61f704
2 changed files with 110 additions and 35 deletions

View File

@ -28,47 +28,58 @@ 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;
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;

View File

@ -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 <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 <doctest-blocks>`)
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 <admonitions>`.
.. 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: