doc: proofread of the all reST sources (no content change)

Normalize reST sources with best practice and KISS in mind.

to name a few points:

- simplify reST tables
- make use of ``literal`` markup for monospace rendering
- fix code-blocks for better rendering in HTML
- normalize section header markup
- limit all lines to a maximum of 79 characters
- add option -H to the sudo command used in code blocks
- drop useless indentation of lists
- ...

[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

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

3 files changed, 122 insertions, 112 deletions

diff --git a/docs/admin/api.rst b/docs/admin/api.rst
index 8d6162247..7804a8664 100644
--- a/docs/admin/api.rst
+++ b/docs/admin/api.rst
@@ -1,94 +1,96 @@
 .. _adminapi:
 
+==================
 Administration API
-------------------
+==================
 
 Get configuration data
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
-.. code:: sh
+.. code:: http
 
-    GET /config
+    GET /config  HTTP/1.1
 
 Sample response
-```````````````
+---------------
+
+.. code:: json
+
+   {
+     "autocomplete": "",
+     "categories": [
+       "map",
+       "it",
+       "images",
+     ],
+     "default_locale": "",
+     "default_theme": "oscar",
+     "engines": [
+       {
+         "categories": [
+           "map"
+         ],
+         "enabled": true,
+         "name": "openstreetmap",
+         "shortcut": "osm"
+       },
+       {
+         "categories": [
+           "it"
+         ],
+         "enabled": true,
+         "name": "arch linux wiki",
+         "shortcut": "al"
+       },
+       {
+         "categories": [
+           "images"
+         ],
+         "enabled": true,
+         "name": "google images",
+         "shortcut": "goi"
+       },
+       {
+         "categories": [
+           "it"
+         ],
+         "enabled": false,
+         "name": "bitbucket",
+         "shortcut": "bb"
+       },
+     ],
+     "instance_name": "searx",
+     "locales": {
+       "de": "Deutsch (German)",
+       "en": "English",
+       "eo": "Esperanto (Esperanto)",
+     },
+     "plugins": [
+       {
+         "enabled": true,
+         "name": "HTTPS rewrite"
+       },
+       {
+         "enabled": false,
+         "name": "Vim-like hotkeys"
+       }
+     ],
+     "safe_search": 0
+   }
 
-.. code:: sh
-    
-    {
-      "autocomplete": "", 
-      "categories": [
-        "map", 
-        "it", 
-        "images", 
-      ], 
-      "default_locale": "", 
-      "default_theme": "oscar", 
-      "engines": [
-        {
-          "categories": [
-            "map"
-          ], 
-          "enabled": true, 
-          "name": "openstreetmap", 
-          "shortcut": "osm"
-        }, 
-        {
-          "categories": [
-            "it"
-          ], 
-          "enabled": true, 
-          "name": "arch linux wiki", 
-          "shortcut": "al"
-        }, 
-        {
-          "categories": [
-            "images"
-          ], 
-          "enabled": true, 
-          "name": "google images", 
-          "shortcut": "goi"
-        }, 
-        {
-          "categories": [
-            "it"
-          ], 
-          "enabled": false, 
-          "name": "bitbucket", 
-          "shortcut": "bb"
-        }, 
-      ], 
-      "instance_name": "searx", 
-      "locales": {
-        "de": "Deutsch (German)", 
-        "en": "English", 
-        "eo": "Esperanto (Esperanto)", 
-      }, 
-      "plugins": [
-        {
-          "enabled": true, 
-          "name": "HTTPS rewrite"
-        }, 
-        {
-          "enabled": false, 
-          "name": "Vim-like hotkeys"
-        }
-      ], 
-      "safe_search": 0
-    }
 
 Embed search bar
-----------------
+================
 
-The search bar can be embedded into websites. Just paste the example into the HTML of the site.
-URL of the searx instance and values are customizable.
+The search bar can be embedded into websites.  Just paste the example into the
+HTML of the site.  URL of the searx instance and values are customizable.
 
 .. code:: html
-    
-    <form method="post" action="https://searx.me/">
-        <!-- search query --> <input type="text" name="q" />
-        <!-- categories   --> <input type="hidden" name="categories" value="general,social media" />
-        <!-- language     --> <input type="hidden" name="lang" value="all" />
-        <!-- locale       --> <input type="hidden" name="locale" value="en" />
-        <!-- date filter  --> <input type="hidden" name="time_range" value="month" />
-    </form>
+
+   <form method="post" action="https://searx.me/">
+     <!-- search      --> <input type="text" name="q" />
+     <!-- categories  --> <input type="hidden" name="categories" value="general,social media" />
+     <!-- language    --> <input type="hidden" name="lang" value="all" />
+     <!-- locale      --> <input type="hidden" name="locale" value="en" />
+     <!-- date filter --> <input type="hidden" name="time_range" value="month" />
+   </form>
diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index 9e55d5968..07dcb9bc5 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -1,25 +1,26 @@
+==========================
 How to protect an instance
 ==========================
 
-Searx depens on external search services. To avoid the abuse of these services it is advised to limit the number of requests processed by searx.
-
-An application firewall, ``filtron`` solves exactly this problem. Information on how to install it can be found at the `project page of filtron <https://github.com/asciimoo/filtron>`__.
-
-Sample configuration of filtron
--------------------------------
+Searx depens on external search services.  To avoid the abuse of these services
+it is advised to limit the number of requests processed by searx.
 
-An example configuration can be find below. This configuration limits the access of
+An application firewall, ``filtron`` solves exactly this problem.  Information
+on how to install it can be found at the `project page of filtron
+<https://github.com/asciimoo/filtron>`__.
 
- * scripts or applications (roboagent limit)
 
- * webcrawlers (botlimit)
-
- * IPs which send too many requests (IP limit)
-
- * too many json, csv, etc. requests (rss/json limit)
+Sample configuration of filtron
+===============================
 
- * the same UserAgent of if too many requests (useragent limit)
+An example configuration can be find below. This configuration limits the access
+of:
 
+- scripts or applications (roboagent limit)
+- webcrawlers (botlimit)
+- IPs which send too many requests (IP limit)
+- too many json, csv, etc. requests (rss/json limit)
+- the same UserAgent of if too many requests (useragent limit)
 
 .. code:: json
 
@@ -120,26 +121,28 @@ An example configuration can be find below. This configuration limits the access
 
 
 Route request through filtron
------------------------------
+=============================
 
 Filtron can be started using the following command:
 
-.. code:: bash
+.. code:: sh
 
-    $ filtron -rules rules.json
+   $ filtron -rules rules.json
 
-It listens on 127.0.0.1:4004 and forwards filtered requests to 127.0.0.1:8888 by default.
+It listens on ``127.0.0.1:4004`` and forwards filtered requests to
+``127.0.0.1:8888`` by default.
 
 Use it along with ``nginx`` with the following example configuration.
 
 .. code:: nginx
 
-    location / {
-        proxy_set_header        Host    $http_host;
-        proxy_set_header        X-Real-IP $remote_addr;
-        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header        X-Scheme $scheme;
-        proxy_pass http://127.0.0.1:4004/;
-    }
+   location / {
+        proxy_set_header   Host    $http_host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Scheme $scheme;
+        proxy_pass         http://127.0.0.1:4004/;
+   }
 
-Requests are coming from port 4004 going through filtron and then forwarded to port 8888 where a searx is being run.
+Requests are coming from port 4004 going through filtron and then forwarded to
+port 8888 where a searx is being run.
diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst
index 49e62bba9..7d7b34492 100644
--- a/docs/admin/morty.rst
+++ b/docs/admin/morty.rst
@@ -1,14 +1,17 @@
+=========================
 How to setup result proxy
 =========================
 
-By default searx can only act as an image proxy for result images,
-but it is possible to proxify all the result URLs with an external service,
-`morty <https://github.com/asciimoo/morty>`__.
+.. _morty: https://github.com/asciimoo/morty
+.. _morty's README: https://github.com/asciimoo/morty
 
-To use this feature, morty has to be installed and activated in searx's ``settings.yml``.
+By default searx can only act as an image proxy for result images, but it is
+possible to proxify all the result URLs with an external service, morty_.
 
-Add the following snippet to your ``settings.yml`` and restart searx:
+To use this feature, morty has to be installed and activated in searx's
+``settings.yml``.
 
+Add the following snippet to your ``settings.yml`` and restart searx:
 
 .. code:: yaml
 
@@ -16,6 +19,8 @@ Add the following snippet to your ``settings.yml`` and restart searx:
         url : http://127.0.0.1:3000/
         key : your_morty_proxy_key
 
-``url`` is the address of the running morty service
+``url``
+  Is the address of the running morty service.
 
-``key`` is an optional argument, see `morty's README <https://github.com/asciimoo/morty>`__ for more information.
+``key``
+  Is an optional argument, see `morty's README`_ for more information.