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>

4 files changed, 97 insertions, 69 deletions

diff --git a/docs/blog/admin.rst b/docs/blog/admin.rst
index 18d5ed33b..e95316192 100644
--- a/docs/blog/admin.rst
+++ b/docs/blog/admin.rst
@@ -1,42 +1,43 @@
-Searx admin interface: manage your instance from your browser
+=============================================================
+Searx admin interface
 =============================================================
 
-One of the biggest advantages of searx is being extremely customizable. But at first it can be daunting to newcomers.
-A barrier of taking advantage of this feature is our ugly settings file which is sometimes hard to understand and edit.
+.. _searx-admin: https://github.com/kvch/searx-admin#searx-admin
+.. _NLnet Foundation: https://nlnet.nl/
 
-To make self-hosting searx more accessible a new tool is introduced, called ``searx-admin``.
-It is a web application which is capable of managing your instance and manipulating its settings via a web UI.
-It aims to replace editing of ``settings.yml`` for less experienced administrators or people
-who prefer graphical admin interfaces.
+  manage your instance from your browser
 
-.. figure:: searx-admin-engines.png
-    :scale: 50 %
-    :alt: Screenshot of engine list
-    :align: center
-    :figclass: align-center
-    
-    Configuration page of engines
+.. sidebar:: Installation
 
+   Installation guide can be found in the repository of searx-admin_.
 
-Since ``searx-admin`` acts as a supervisor for searx, we have decided to implement it
-as a standalone tool instead of part of searx. Another reason for making it a standalone
-tool is that the codebase and dependencies of searx should not grow because of a fully optional feature,
-which does not affect existing instances.
+One of the biggest advantages of searx is being extremely customizable. But at
+first it can be daunting to newcomers.  A barrier of taking advantage of this
+feature is our ugly settings file which is sometimes hard to understand and
+edit.
 
+To make self-hosting searx more accessible a new tool is introduced, called
+``searx-admin``.  It is a web application which is capable of managing your
+instance and manipulating its settings via a web UI.  It aims to replace editing
+of ``settings.yml`` for less experienced administrators or people who prefer
+graphical admin interfaces.
 
-Installation
-------------
+.. figure:: searx-admin-engines.png
+   :alt: Screenshot of engine list
 
-Installation guide can be found in the repository of searx-admin:
-https://github.com/kvch/searx-admin#installation--usage
+   Configuration page of engines
 
-Acknowledgements
-----------------
+Since ``searx-admin`` acts as a supervisor for searx, we have decided to
+implement it as a standalone tool instead of part of searx.  Another reason for
+making it a standalone tool is that the codebase and dependencies of searx
+should not grow because of a fully optional feature, which does not affect
+existing instances.
 
-This development was sponsored by `NLnet Foundation`_.
 
-.. _NLnet Foundation: https://nlnet.nl/
+Acknowledgements
+================
 
+This development was sponsored by `NLnet Foundation`_.
 
 | Happy hacking.
 | kvch // 2017.08.22 21:25
diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst
index 2ccaaa5d3..52fa3f126 100644
--- a/docs/blog/blog.rst
+++ b/docs/blog/blog.rst
@@ -1,3 +1,4 @@
+====
 Blog
 ====
 
diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst
index 0def3e09a..f6e90de3a 100644
--- a/docs/blog/intro-offline.rst
+++ b/docs/blog/intro-offline.rst
@@ -1,58 +1,70 @@
+===============================
 Preparation for offline engines
 ===============================
 
 Offline engines
----------------
+===============
 
-To extend the functionality of searx, offline engines are going to be introduced. An offline engine is an engine which does not need Internet connection to perform a search and does not use HTTP to communicate.
+To extend the functionality of searx, offline engines are going to be
+introduced.  An offline engine is an engine which does not need Internet
+connection to perform a search and does not use HTTP to communicate.
 
-Offline engines can be configured as online engines, by adding those to the `engines` list of `settings.yml`. Thus, searx finds the engine file and imports it.
+Offline engines can be configured as online engines, by adding those to the
+`engines` list of :origin:`settings.yml <searx/settings.yml>`.  Thus, searx
+finds the engine file and imports it.
 
 Example skeleton for the new engines:
 
 .. code:: python
 
-    from subprocess import PIPE, Popen
+   from subprocess import PIPE, Popen
 
-    categories = ['general']
-    offline = True
+   categories = ['general']
+   offline = True
 
-    def init(settings):
-        pass
+   def init(settings):
+       pass
 
-    def search(query, params):
-        process = Popen(['ls', query], stdout=PIPE)
-        return_code = process.wait()
-        if return_code != 0:
-            raise RuntimeError('non-zero return code', return_code)
+   def search(query, params):
+       process = Popen(['ls', query], stdout=PIPE)
+       return_code = process.wait()
+       if return_code != 0:
+           raise RuntimeError('non-zero return code', return_code)
 
-        results = []
-        line = process.stdout.readline()
-        while line:
-            result = parse_line(line)
-            results.append(results)
+       results = []
+       line = process.stdout.readline()
+       while line:
+           result = parse_line(line)
+           results.append(results)
 
-            line = process.stdout.readline()
+           line = process.stdout.readline()
 
-        return results
+       return results
 
 
 Development progress
---------------------
+====================
 
-First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: :wiki:`Offline-engines`.
+First, a proposal has been created as a Github issue.  Then it was moved to the
+wiki as a design document.  You can read it here: :wiki:`Offline-engines`.
 
-In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests.
+In this development step, searx core was prepared to accept and perform offline
+searches.  Offline search requests are scheduled together with regular offline
+requests.
 
-As offline searches can return arbitrary results depending on the engine, the current result templates were insufficient to present such results. Thus, a new template is introduced which is caplable of presenting arbitrary key value pairs as a table. You can check out the pull request for more details: https://github.com/asciimoo/searx/pull/1700
+As offline searches can return arbitrary results depending on the engine, the
+current result templates were insufficient to present such results.  Thus, a new
+template is introduced which is caplable of presenting arbitrary key value pairs
+as a table. You can check out the pull request for more details see
+:pull:`1700`.
 
 Next steps
-----------
+==========
 
 Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines.
 
 Acknowledgement
----------------
+===============
 
 This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
 
diff --git a/docs/blog/python3.rst b/docs/blog/python3.rst
index eb14a49eb..5bb7f1c80 100644
--- a/docs/blog/python3.rst
+++ b/docs/blog/python3.rst
@@ -1,7 +1,17 @@
-Introducing Python3 support
-===========================
+============================
+Introducing Python 3 support
+============================
 
-As most operation systems are coming with Python3 installed by default. So it is time for searx to support Python3. But don't worry support of Python2.7 won't be dropped.
+.. _Python 2.7 clock: https://pythonclock.org/
+
+.. sidebar:: Python 2.7 to 3 upgrade
+
+   This chapter exists of historical reasons.  Python 2.7 release schedule ends
+   (`Python 2.7 clock`_) after 11 years Python 3 exists
+
+As most operation systems are coming with Python3 installed by default. So it is
+time for searx to support Python3.  But don't worry support of Python2.7 won't be
+dropped.
 
 .. image:: searxpy3.png
     :scale: 50 %
@@ -9,13 +19,14 @@ As most operation systems are coming with Python3 installed by default. So it is
     :align: center
 
 
-How to run searx using Python3
-------------------------------
+How to run searx using Python 3
+===============================
 
-Please make sure that you run at least Python3.5.
+Please make sure that you run at least Python 3.5.
 
-To run searx, first a Python3 virtualenv should be created. After entering the virtualenv,
-dependencies must be installed. Then run searx with python3 instead of the usual python command.
+To run searx, first a Python3 virtualenv should be created.  After entering the
+virtualenv, dependencies must be installed. Then run searx with python3 instead
+of the usual python command.
 
 .. code:: sh
 
@@ -25,25 +36,28 @@ dependencies must be installed. Then run searx with python3 instead of the usual
     python3 searx/webapp.py
 
 
-If you want to run searx using Python2.7, you don't have to do anything differently as before.
+If you want to run searx using Python2.7, you don't have to do anything
+differently as before.
 
 Fun facts
----------
+=========
 
 - 115 files were changed when implementing the support for both Python versions.
 
-- All of the dependencies was compatible except for the robotframework used for browser tests. Thus, these tests were migrated to splinter. So from now on both versions are being tested on Travis and can be tested locally.
+- All of the dependencies was compatible except for the robotframework used for
+  browser tests.  Thus, these tests were migrated to splinter. So from now on
+  both versions are being tested on Travis and can be tested locally.
 
-If you found bugs...
---------------------
+If you found bugs
+=================
 
-...please open an issue on `GitHub`_. Make sure that you mention your Python version in your issue,
-so we can investigate it properly.
+Please open an issue on `GitHub`_.  Make sure that you mention your Python
+version in your issue, so we can investigate it properly.
 
 .. _GitHub: https://github.com/asciimoo/searx/issues
 
-Acknowledgement
----------------
+Acknowledgment
+==============
 
 This development was sponsored by `NLnet Foundation`_.