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*
-  one asterisk for emphasis
+.. sidebar:: Inline markup
 
-``**boldface**`` -- **boldface**
-  two asterisks for strong emphasis and
+   - :ref:`reST roles`
+   - :ref:`reST smart ref`
 
-````foo()```` -- ``foo()``
-  backquotes for code samples and literals.
+Basic inline markup is done with asterisks and backquotes.  If asterisks or
+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
-  inline markup delimiters, they have to be escaped with a backslash (``\*foo is
-  a pointer``).
+================================================ ==================== ========================
+description                                      rendered             markup
+================================================ ==================== ========================
+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,44 +114,82 @@ 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
-   :class: rst-example
+reST template
+-------------
 
-   .. code:: reST
+reST template for an simple article:
+
+.. code:: reST
+
+    .. _doc refname:
+
+    ==============
+    Document title
+    ==============
+
+    Lorem ipsum dolor sit amet, consectetur adipisici elit ..  Further read
+    :ref:`chapter refname`.
+
+    .. _chapter refname:
+
+    Chapter
+    =======
+
+    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+    aliquid ex ea commodi consequat ...
+
+    .. _section refname:
+
+    Section
+    -------
 
-       .. _document title:
+    lorem ..
+
+    .. _subsection refname:
+
+    Subsection
+    ~~~~~~~~~~
+
+    lorem ..
+
+
+Headings
+--------
+
+#. title - with overline for document title:
+
+  .. code:: reST
+
+    ==============
+    Document title
+    ==============
+
+
+#. chapter - with anchor named ``anchor name``:
+
+   .. code:: reST
 
-       ==============
-       Document title
-       ==============
+      .. _anchor name:
 
-       Lorem ipsum dolor sit amet, consectetur adipisici elit ..
-       Further read :ref:`chapter title`.
+      Chapter
+      =======
 
-       .. _chapter title:
+#. section
 
-       Chapters
-       ========
+   .. code:: reST
 
-       Ut enim ad minim veniam, quis nostrud exercitation ullamco
-       laboris nisi ut aliquid ex ea commodi consequat ...
+      Section
+      -------
 
-       Section
-       -------
+#. subsection
 
-       lorem ..
+   .. code:: reST
 
-       Subsection
-       ~~~~~~~~~~
+      Subsection
+      ~~~~~~~~~~
 
-       lorem ..
 
 
 Anchors & Links
@@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup:
 
 .. code:: reST
 
-   Visit chapter :ref:`reST anchor`.
-   Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
+   Visit chapter :ref:`reST anchor`.  Or set hyperlink text manualy :ref:`foo
+   bar <reST anchor>`.
 
 .. admonition:: ``:ref:`` role
    :class: rst-example
 
-   Visist chapter :ref:`reST anchor`
-   Or set hyperlink text manualy :ref:`foo bar <reST anchor>`.
+   Visist chapter :ref:`reST anchor`.  Or set hyperlink text manualy :ref:`foo
+   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`,
-:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,
-:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
+Sidebar
+-------
+
+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 ..