docs: reST-primer continued proofreading (WIP)

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/dev/reST.rst

@@ -88,19 +88,23 @@ Developer's POV: :origin:`docs/dev`
 Basic inline markup
 ===================
 
-``*italics*`` -- *italics*
+.. sidebar:: Inline markup
-  one asterisk for emphasis
 
-``**boldface**`` -- **boldface**
+   - :ref:`reST roles`
-  two asterisks for strong emphasis and
+   - :ref:`reST smart ref`
 
-````foo()```` -- ``foo()``
+Basic inline markup is done with asterisks and backquotes.  If asterisks or
-  backquotes for code samples and literals.
+backquotes appear in running text and could be confused with inline markup
+delimiters, they have to be escaped with a backslash (``\*pointer``).
 
-``\*foo is a pointer`` -- \*foo is a pointer
+================================================ ==================== ========================
-  If asterisks or backquotes appear in running text and could be confused with
+description                                      rendered             markup
-  inline markup delimiters, they have to be escaped with a backslash (``\*foo is
+================================================ ==================== ========================
-  a pointer``).
+one asterisk for emphasis                        *italics*            ``*italics*``
+two asterisks for strong emphasis                **boldface**         ``**boldface**``
+backquotes for code samples and literals         ``foo()``            ````foo()````
+quote asterisks or backquotes                    \*foo is a pointer   ``\*foo is a pointer``
+================================================ ==================== ========================
 
 .. _reST basic structure:
 
@@ -110,46 +114,84 @@ Basic article structure
 The basic structure of an article makes use of heading adornments to markup
 chapter, sections and subsections.
 
-#. ``=`` with overline for document title
-#. ``=`` for chapters
-#. ``-`` for sections
-#. ``~`` for subsections
-
 .. _reST template:
 
-.. admonition:: reST template
+reST template
-   :class: rst-example
+-------------
+
+reST template for an simple article:
 
 .. code:: reST
 
-       .. _document title:
+    .. _doc refname:
 
     ==============
     Document title
     ==============
 
-       Lorem ipsum dolor sit amet, consectetur adipisici elit ..
+    Lorem ipsum dolor sit amet, consectetur adipisici elit ..  Further read
-       Further read :ref:`chapter title`.
+    :ref:`chapter refname`.
 
-       .. _chapter title:
+    .. _chapter refname:
 
-       Chapters
+    Chapter
-       ========
+    =======
 
-       Ut enim ad minim veniam, quis nostrud exercitation ullamco
+    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-       laboris nisi ut aliquid ex ea commodi consequat ...
+    aliquid ex ea commodi consequat ...
+
+    .. _section refname:
 
     Section
     -------
 
     lorem ..
 
+    .. _subsection refname:
+
     Subsection
     ~~~~~~~~~~
 
     lorem ..
 
 
+Headings
+--------
+
+#. title - with overline for document title:
+
+  .. code:: reST
+
+    ==============
+    Document title
+    ==============
+
+
+#. chapter - with anchor named ``anchor name``:
+
+   .. code:: reST
+
+      .. _anchor name:
+
+      Chapter
+      =======
+
+#. section
+
+   .. code:: reST
+
+      Section
+      -------
+
+#. subsection
+
+   .. code:: reST
+
+      Subsection
+      ~~~~~~~~~~
+
+
+
 Anchors & Links
 ===============
 
@@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup:
 
 .. code:: reST
 
-   Visit chapter :ref:`reST anchor`.
+   Visit chapter :ref:`reST anchor`.  Or set hyperlink text manualy :ref:`foo
-   Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
+   bar <reST anchor>`.
 
 .. admonition:: ``:ref:`` role
    :class: rst-example
 
-   Visist chapter :ref:`reST anchor`
+   Visist chapter :ref:`reST anchor`.  Or set hyperlink text manualy :ref:`foo
-   Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
+   bar <reST anchor>`.
 
 .. _reST ordinary ref:
 
-link ordinary URL
+Link ordinary URL
 -----------------
 
 If you need to reference external URLs use *named* hyperlinks to maintain
@@ -221,8 +263,8 @@ readability of reST sources.  Here is a example taken from *this* article:
 
 .. _reST smart ref:
 
-smart references
+Smart refs
-----------------
+----------
 
 With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
 content becomes smart.
@@ -270,6 +312,8 @@ To list all anchors of the inventory (e.g. ``python``) use:
    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
 
 
+.. _reST roles:
+
 Roles
 =====
 
@@ -634,9 +678,24 @@ Further list blocks
 Admonitions
 ===========
 
-Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
+Sidebar
-:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,
+-------
-:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
+
+Sidebar is an eye catcher, often used for admonitions pointing further stuff or
+site effects.  Here is the source of the sidebar :ref:`on top of this page <reST
+primer>`.
+
+.. code:: reST
+
+   .. sidebar:: KISS_ and readability_
+
+      Instead of defining more and more roles, we at searx encourage our
+      contributors to follow principles like KISS_ and readability_.
+
+Generic admonition
+------------------
+
+The generic :dudir:`admonition <admonitions>` needs a title:
 
 .. code:: reST
 
@@ -644,6 +703,21 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
 
       lorem ipsum ..
 
+
+.. admonition:: generic admonition title
+
+   lorem ipsum ..
+
+
+Specific admonitions
+--------------------
+
+Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
+:dudir:`warning` .
+
+.. code:: reST
+
    .. hint::
 
       lorem ipsum ..
@@ -657,10 +731,6 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
       lorem ipsum ..
 
 
-.. admonition:: generic admonition title
-
-   lorem ipsum ..
-
 .. hint::
 
    lorem ipsum ..