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>

6 files changed, 414 insertions, 549 deletions

diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst
index 65e587294..9414de2c9 100644
--- a/docs/dev/contribution_guide.rst
+++ b/docs/dev/contribution_guide.rst
@@ -1,66 +1,68 @@
+=================
 How to contribute
------------------
+=================
 
 Prime directives: Privacy, Hackability
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+======================================
 
-Searx has two prime directives, privacy-by-design and hackability. The
+Searx has two prime directives, **privacy-by-design and hackability** .  The
 hackability comes in three levels:
 
--  support of search engines
--  plugins to alter search behaviour
--  hacking searx itself
+- support of search engines
+- plugins to alter search behaviour
+- hacking searx itself
 
-Note the lack of "world domination" among the directives.
-Searx has no intention of wide mass-adoption, rounded
-corners, etc. The prime directive "privacy" deserves a separate
-chapter, as it's quite uncommon unfortunately.
+Note the lack of "world domination" among the directives.  Searx has no
+intention of wide mass-adoption, rounded corners, etc.  The prime directive
+"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
 
 Privacy-by-design
-^^^^^^^^^^^^^^^^^
+-----------------
 
-Searx was born out of the need for a privacy-respecting search tool
-which can be extended easily to maximize both its search and its
-privacy protecting capabilities.
+Searx was born out of the need for a **privacy-respecting** search tool which
+can be extended easily to maximize both, its search and its privacy protecting
+capabilities.
 
-A few widely used features work differently or turned off by default or not implemented
-at all as a consequence of privacy-by-design.
+A few widely used features work differently or turned off by default or not
+implemented at all **as a consequence of privacy-by-design**.
 
-If a feature reduces the privacy preserving aspects of searx, it
-should be switched off by default or should not implemented at all.
-There are plenty of search engines already providing such features.
-If a feature reduces the protection of searx, users must be
-informed about the effect of choosing to enable it. Features
-that protect privacy but differ from the expectations of the
-user should also be explained.
+If a feature reduces the privacy preserving aspects of searx, it should be
+switched off by default or should not implemented at all.  There are plenty of
+search engines already providing such features.  If a feature reduces the
+protection of searx, users must be informed about the effect of choosing to
+enable it.  Features that protect privacy but differ from the expectations of
+the user should also be explained.
 
-Also, if you think that something works weird with searx,
-it's might be because of the tool you use is designed in a way to interfere with
-the privacy respect. Submitting a bugreport to the vendor of the tool that
-misbehaves might be a good feedback to reconsider the disrespect to
-its customers (e.g. GET vs POST requests in various browsers).
+Also, if you think that something works weird with searx, it's might be because
+of the tool you use is designed in a way to interfere with the privacy respect.
+Submitting a bugreport to the vendor of the tool that misbehaves might be a good
+feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
+requests in various browsers).
 
-Remember the other prime directive of searx is to be hackable, so if the
-above privacy concerns do not fancy you, simply fork it.
+Remember the other prime directive of searx is to be hackable, so if the above
+privacy concerns do not fancy you, simply fork it.
 
-Happy hacking.
+  *Happy hacking.*
 
 Code
-~~~~
+====
+
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+
 
 In order to submit a patch, please follow the steps below:
 
 - Follow coding conventions.
 
-  - PEP8 standards apply, except the convention of line length
-
+  - PEP8_ standards apply, except the convention of line length
   - Maximum line length is 120 characters
 
-- Check if your code breaks existing tests. If so, update the tests or fix your code.
+- Check if your code breaks existing tests.  If so, update the tests or fix your
+  code.
 
 - If your code can be unit-tested, add unit tests.
 
-- Add yourself to the AUTHORS file.
+- Add yourself to the :origin:`AUTHORS.rst` file.
 
 - Create a pull request.
 
@@ -68,31 +70,20 @@ For more help on getting started with searx development, see :ref:`devquickstart
 
 
 Translation
-~~~~~~~~~~~
+===========
 
-Translation currently takes place on
-`transifex <https://transifex.com/projects/p/searx>`__.
+Translation currently takes place on :ref:`transifex <translation>`.
 
-**Please, do not update translation files in the repo.**
+.. caution::
 
-Documentation
-~~~~~~~~~~~~~
+   Please, do not update translation files in the repo.
 
-The documentation is built using Sphinx. So in order to be able to generate the required
-files, you have to install it on your system. (It can be installed easily using pip.)
 
-1. Checkout the gh-pages branch.
-
-2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.
-
-3. Build the documentation using Sphinx.
-
-4. Add the updated and created files of these extension:
-
-   - .rst
+Documentation
+=============
 
-   - .html
+.. admonition::  ToDo
 
-   - .txt
+   docs are no longer in gh-branch
 
-6. Create a pull request.
+   Update this chapter and document the /docs workflow!!
diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst
index 937ca8880..92405dc64 100644
--- a/docs/dev/engine_overview.rst
+++ b/docs/dev/engine_overview.rst
@@ -1,21 +1,25 @@
+
+.. _engines-dev:
+
+===============
 Engine overview
 ===============
 
+.. _metasearch-engine: https://en.wikipedia.org/wiki/Metasearch_engine
 
-searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
-so it uses different search engines to provide better results.
-
-Because there is no general search API which could be used for every
-search engine, an adapter has to be built between searx and the
-external search engines. Adapters are stored under the folder
-:origin:`searx/engines`.
+searx is a metasearch-engine_, so it uses different search engines to provide
+better results.
 
+Because there is no general search API which could be used for every search
+engine, an adapter has to be built between searx and the external search
+engines.  Adapters are stored under the folder :origin:`searx/engines`.
 
 .. contents::
    :depth: 3
+   :backlinks: entry
 
 general engine configuration
-----------------------------
+============================
 
 It is required to tell searx the type of results the engine provides. The
 arguments can be set in the engine file or in the settings file
@@ -23,292 +27,239 @@ arguments can be set in the engine file or in the settings file
 the ones in the engine file.
 
 It does not matter if an option is stored in the engine file or in the
-settings. However, the standard way is the following:
+settings.  However, the standard way is the following:
 
 
 engine file
-~~~~~~~~~~~
-
-+----------------------+-----------+-----------------------------------------+
-| argument             | type      | information                             |
-+======================+===========+=========================================+
-| categories           | list      | pages, in which the engine is working   |
-+----------------------+-----------+-----------------------------------------+
-| paging               | boolean   | support multible pages                  |
-+----------------------+-----------+-----------------------------------------+
-| language\_support    | boolean   | support language choosing               |
-+----------------------+-----------+-----------------------------------------+
-| time\_range\_support | boolean   | support search time range               |
-+----------------------+-----------+-----------------------------------------+
-| offline              | boolean   | engine runs offline                     |
-+----------------------+-----------+-----------------------------------------+
+-----------
+
+======================= =========== ===========================================
+argument                type        information
+======================= =========== ===========================================
+categories              list        pages, in which the engine is working
+paging                  boolean     support multible pages
+language_support        boolean     support language choosing
+time_range_support      boolean     support search time range
+offline                 boolean     engine runs offline
+======================= =========== ===========================================
+
 
 settings.yml
-~~~~~~~~~~~~
-
-+------------+----------+-----------------------------------------------+
-| argument   | type     | information                                   |
-+============+==========+===============================================+
-| name       | string   | name of search-engine                         |
-+------------+----------+-----------------------------------------------+
-| engine     | string   | name of searx-engine (filename without .py)   |
-+------------+----------+-----------------------------------------------+
-| shortcut   | string   | shortcut of search-engine                     |
-+------------+----------+-----------------------------------------------+
-| timeout    | string   | specific timeout for search-engine            |
-+------------+----------+-----------------------------------------------+
+------------
+
+======================= =========== ===========================================
+argument                type        information
+======================= =========== ===========================================
+name                    string      name of search-engine
+engine                  string      name of searx-engine
+                                    (filename without ``.py``)
+shortcut                string      shortcut of search-engine
+timeout                 string      specific timeout for search-engine
+======================= =========== ===========================================
+
 
 overrides
-~~~~~~~~~
-
-A few of the options have default values in the engine, but are
-often overwritten by the settings. If ``None`` is assigned to an option
-in the engine file, it has to be redefined in the settings,
-otherwise searx will not start with that engine.
-
-The naming of overrides is arbitrary. But the recommended
-overrides are the following:
-
-+-----------------------+----------+----------------------------------------------------------------+
-| argument              | type     | information                                                    |
-+=======================+==========+================================================================+
-| base\_url             | string   | base-url, can be overwritten to use same engine on other URL   |
-+-----------------------+----------+----------------------------------------------------------------+
-| number\_of\_results   | int      | maximum number of results per request                          |
-+-----------------------+----------+----------------------------------------------------------------+
-| language              | string   | ISO code of language and country like en\_US                   |
-+-----------------------+----------+----------------------------------------------------------------+
-| api\_key              | string   | api-key if required by engine                                  |
-+-----------------------+----------+----------------------------------------------------------------+
+---------
+
+A few of the options have default values in the engine, but are often
+overwritten by the settings.  If ``None`` is assigned to an option in the engine
+file, it has to be redefined in the settings, otherwise searx will not start
+with that engine.
+
+The naming of overrides is arbitrary.  But the recommended overrides are the
+following:
+
+======================= =========== ===========================================
+argument                type        information
+======================= =========== ===========================================
+base_url                string      base-url, can be overwritten to use same
+                                    engine on other URL
+number_of_results       int         maximum number of results per request
+language                string      ISO code of language and country like en_US
+api_key                 string      api-key if required by engine
+======================= =========== ===========================================
 
 example code
-~~~~~~~~~~~~
+------------
 
 .. code:: python
 
-    # engine dependent config
-    categories = ['general']
-    paging = True
-    language_support = True
+   # engine dependent config
+   categories = ['general']
+   paging = True
+   language_support = True
+
 
 making a request
-----------------
+================
 
-To perform a search an URL have to be specified. In addition to
-specifying an URL, arguments can be passed to the query.
+To perform a search an URL have to be specified.  In addition to specifying an
+URL, arguments can be passed to the query.
 
 passed arguments
-~~~~~~~~~~~~~~~~
+----------------
 
-These arguments can be used to construct the search query. Furthermore,
+These arguments can be used to construct the search query.  Furthermore,
 parameters with default value can be redefined for special purposes.
 
-+----------------------+------------+------------------------------------------------------------------------+
-| argument             | type       | default-value, information                                             |
-+======================+============+========================================================================+
-| url                  | string     | ``''``                                                                 |
-+----------------------+------------+------------------------------------------------------------------------+
-| method               | string     | ``'GET'``                                                              |
-+----------------------+------------+------------------------------------------------------------------------+
-| headers              | set        | ``{}``                                                                 |
-+----------------------+------------+------------------------------------------------------------------------+
-| data                 | set        | ``{}``                                                                 |
-+----------------------+------------+------------------------------------------------------------------------+
-| cookies              | set        | ``{}``                                                                 |
-+----------------------+------------+------------------------------------------------------------------------+
-| verify               | boolean    | ``True``                                                               |
-+----------------------+------------+------------------------------------------------------------------------+
-| headers.User-Agent   | string     | a random User-Agent                                                    |
-+----------------------+------------+------------------------------------------------------------------------+
-| category             | string     | current category, like ``'general'``                                   |
-+----------------------+------------+------------------------------------------------------------------------+
-| started              | datetime   | current date-time                                                      |
-+----------------------+------------+------------------------------------------------------------------------+
-| pageno               | int        | current pagenumber                                                     |
-+----------------------+------------+------------------------------------------------------------------------+
-| language             | string     | specific language code like ``'en_US'``, or ``'all'`` if unspecified   |
-+----------------------+------------+------------------------------------------------------------------------+
+====================== ============ ========================================================================
+argument               type         default-value, information
+====================== ============ ========================================================================
+url                    string       ``''``
+method                 string       ``'GET'``
+headers                set          ``{}``
+data                   set          ``{}``
+cookies                set          ``{}``
+verify                 boolean      ``True``
+headers.User-Agent     string       a random User-Agent
+category               string       current category, like ``'general'``
+started                datetime     current date-time
+pageno                 int          current pagenumber
+language               string       specific language code like ``'en_US'``, or ``'all'`` if unspecified
+====================== ============ ========================================================================
 
 parsed arguments
-~~~~~~~~~~~~~~~~
-
-The function ``def request(query, params):`` always returns the
-``params`` variable. Inside searx, the following paramters can be
-used to specify a search request:
-
-+------------+-----------+---------------------------------------------------------+
-| argument   | type      | information                                             |
-+============+===========+=========================================================+
-| url        | string    | requested url                                           |
-+------------+-----------+---------------------------------------------------------+
-| method     | string    | HTTP request method                                     |
-+------------+-----------+---------------------------------------------------------+
-| headers    | set       | HTTP header information                                 |
-+------------+-----------+---------------------------------------------------------+
-| data       | set       | HTTP data information (parsed if ``method != 'GET'``)   |
-+------------+-----------+---------------------------------------------------------+
-| cookies    | set       | HTTP cookies                                            |
-+------------+-----------+---------------------------------------------------------+
-| verify     | boolean   | Performing SSL-Validity check                           |
-+------------+-----------+---------------------------------------------------------+
+----------------
+
+The function ``def request(query, params):`` always returns the ``params``
+variable.  Inside searx, the following paramters can be used to specify a search
+request:
+
+============ =========== =========================================================
+argument     type        information
+============ =========== =========================================================
+url          string      requested url
+method       string      HTTP request method
+headers      set         HTTP header information
+data         set         HTTP data information (parsed if ``method != 'GET'``)
+cookies      set         HTTP cookies
+verify       boolean     Performing SSL-Validity check
+============ =========== =========================================================
+
 
 example code
-~~~~~~~~~~~~
+------------
 
 .. code:: python
 
-    # search-url
-    base_url = 'https://example.com/'
-    search_string = 'search?{query}&page={page}'
+   # search-url
+   base_url = 'https://example.com/'
+   search_string = 'search?{query}&page={page}'
 
-    # do search-request
-    def request(query, params):
-        search_path = search_string.format(
-            query=urlencode({'q': query}),
-            page=params['pageno'])
+   # do search-request
+   def request(query, params):
+       search_path = search_string.format(
+           query=urlencode({'q': query}),
+           page=params['pageno'])
 
-        params['url'] = base_url + search_path
+       params['url'] = base_url + search_path
+
+       return params
 
-        return params
 
 returned results
-----------------
+================
 
-Searx is able to return results of different media-types.
-Currently the following media-types are supported:
+Searx is able to return results of different media-types.  Currently the
+following media-types are supported:
 
--  default
--  images
--  videos
--  torrent
--  map
+- default_
+- images_
+- videos_
+- torrent_
+- map_
 
-To set another media-type as default, the parameter
-``template`` must be set to the desired type.
+To set another media-type as default, the parameter ``template`` must be set to
+the desired type.
 
 default
-~~~~~~~
-
-+--------------------+---------------------------------------------------------------------------------------------------------------+
-| result-parameter   | information                                                                                                   |
-+====================+===============================================================================================================+
-| url                | string, url of the result                                                                                     |
-+--------------------+---------------------------------------------------------------------------------------------------------------+
-| title              | string, title of the result                                                                                   |
-+--------------------+---------------------------------------------------------------------------------------------------------------+
-| content            | string, general result-text                                                                                   |
-+--------------------+---------------------------------------------------------------------------------------------------------------+
-| publishedDate      | :py:class:`datetime.datetime`, time of publish                                                                |
-+--------------------+---------------------------------------------------------------------------------------------------------------+
+-------
+
+========================= =====================================================
+result-parameter          information
+========================= =====================================================
+url                       string, url of the result
+title                     string, title of the result
+content                   string, general result-text
+publishedDate             :py:class:`datetime.datetime`, time of publish
+========================= =====================================================
 
 images
-~~~~~~
-
-to use this template, the parameter
-
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| result-parameter   | information                                                                                                                           |
-+====================+=======================================================================================================================================+
-| template           | is set to ``images.html``                                                                                                             |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| url                | string, url to the result site                                                                                                        |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| title              | string, title of the result *(partly implemented)*                                                                                    |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| content            | *(partly implemented)*                                                                                                                |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| publishedDate      | :py:class:`datetime.datetime`, time of publish *(partly implemented)*                                                                 |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| img\_src           | string, url to the result image                                                                                                       |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| thumbnail\_src     | string, url to a small-preview image                                                                                                  |
-+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+------
+
+To use this template, the parameter:
+
+========================= =====================================================
+result-parameter          information
+========================= =====================================================
+template                  is set to ``images.html``
+url                       string, url to the result site
+title                     string, title of the result *(partly implemented)*
+content                   *(partly implemented)*
+publishedDate             :py:class:`datetime.datetime`,
+                          time of publish *(partly implemented)*
+img\_src                  string, url to the result image
+thumbnail\_src            string, url to a small-preview image
+========================= =====================================================
 
 videos
-~~~~~~
-
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| result-parameter   | information                                                                                                  |
-+====================+==============================================================================================================+
-| template           | is set to ``videos.html``                                                                                    |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| url                | string, url of the result                                                                                    |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| title              | string, title of the result                                                                                  |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| content            | *(not implemented yet)*                                                                                      |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| publishedDate      | :py:class:`datetime.datetime`, time of publish                                                               |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
-| thumbnail          | string, url to a small-preview image                                                                         |
-+--------------------+--------------------------------------------------------------------------------------------------------------+
+------
+
+========================= =====================================================
+result-parameter          information
+========================= =====================================================
+template                  is set to ``videos.html``
+url                       string, url of the result
+title                     string, title of the result
+content                   *(not implemented yet)*
+publishedDate             :py:class:`datetime.datetime`, time of publish
+thumbnail                 string, url to a small-preview image
+========================= =====================================================
 
 torrent
-~~~~~~~
-
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| result-parameter | information                                                                                                                           |
-+==================+=======================================================================================================================================+
-| template         | is set to ``torrent.html``                                                                                                            |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| url              | string, url of the result                                                                                                             |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| title            | string, title of the result                                                                                                           |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| content          | string, general result-text                                                                                                           |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| publishedDate    | :py:class:`datetime.datetime`, time of publish *(not implemented yet)*                                                                |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| seed             | int, number of seeder                                                                                                                 |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| leech            | int, number of leecher                                                                                                                |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| filesize         | int, size of file in bytes                                                                                                            |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| files            | int, number of files                                                                                                                  |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| magnetlink       | string, `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ of the result                                                |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| torrentfile      | string, torrentfile of the result                                                                                                     |
-+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+-------
+
+.. _magnetlink: https://en.wikipedia.org/wiki/Magnet_URI_scheme
+
+========================= =====================================================
+result-parameter          information
+========================= =====================================================
+template                  is set to ``torrent.html``
+url                       string, url of the result
+title                     string, title of the result
+content                   string, general result-text
+publishedDate             :py:class:`datetime.datetime`,
+                          time of publish *(not implemented yet)*
+seed                      int, number of seeder
+leech                     int, number of leecher
+filesize                  int, size of file in bytes
+files                     int, number of files
+magnetlink                string, magnetlink_ of the result
+torrentfile               string, torrentfile of the result
+========================= =====================================================
 
 
 map
-~~~
-
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| result-parameter        | information                                                                                                  |
-+=========================+==============================================================================================================+
-| url                     | string, url of the result                                                                                    |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| title                   | string, title of the result                                                                                  |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| content                 | string, general result-text                                                                                  |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| publishedDate           | :py:class:`datetime.datetime`, time of publish                                                               |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| latitude                | latitude of result (in decimal format)                                                                       |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| longitude               | longitude of result (in decimal format)                                                                      |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| boundingbox             | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``)                          |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| geojson                 | geojson of result (http://geojson.org)                                                                       |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| osm.type                | type of osm-object (if OSM-Result)                                                                           |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| osm.id                  | id of osm-object (if OSM-Result)                                                                             |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.name            | name of object                                                                                               |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.road            | street name of object                                                                                        |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.house\_number   | house number of object                                                                                       |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.locality        | city, place of object                                                                                        |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.postcode        | postcode of object                                                                                           |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| address.country         | country of object                                                                                            |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-
+---
+
+========================= =====================================================
+result-parameter          information
+========================= =====================================================
+url                       string, url of the result
+title                     string, title of the result
+content                   string, general result-text
+publishedDate             :py:class:`datetime.datetime`, time of publish
+latitude                  latitude of result (in decimal format)
+longitude                 longitude of result (in decimal format)
+boundingbox               boundingbox of result (array of 4. values
+                          ``[lat-min, lat-max, lon-min, lon-max]``)
+geojson                   geojson of result (http://geojson.org)
+osm.type                  type of osm-object (if OSM-Result)
+osm.id                    id of osm-object (if OSM-Result)
+address.name              name of object
+address.road              street name of object
+address.house_number      house number of object
+address.locality          city, place of object
+address.postcode          postcode of object
+address.country           country of object
+========================= =====================================================
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index 1d77f8611..e97bbeb4a 100644
--- a/docs/dev/plugins.rst
+++ b/docs/dev/plugins.rst
@@ -1,45 +1,48 @@
+=======
 Plugins
--------
+=======
 
-Plugins can extend or replace functionality of various components of
-searx.
+Plugins can extend or replace functionality of various components of searx.
 
 Example plugin
-~~~~~~~~~~~~~~
+==============
 
 .. code:: python
 
-    name = 'Example plugin'
-    description = 'This plugin extends the suggestions with the word "example"'
-    default_on = False  # disabled by default
+   name = 'Example plugin'
+   description = 'This plugin extends the suggestions with the word "example"'
+   default_on = False  # disabled by default
 
-    js_dependencies = tuple()  # optional, list of static js files
-    css_dependencies = tuple()  # optional, list of static css files
+   js_dependencies = tuple()  # optional, list of static js files
+   css_dependencies = tuple()  # optional, list of static css files
 
 
-    # attach callback to the post search hook
-    #  request: flask request object
-    #  ctx: the whole local context of the post search hook
-    def post_search(request, ctx):
-        ctx['search'].suggestions.add('example')
-        return True
+   # attach callback to the post search hook
+   #  request: flask request object
+   #  ctx: the whole local context of the post search hook
+   def post_search(request, ctx):
+       ctx['search'].suggestions.add('example')
+       return True
 
 Plugin entry points
-~~~~~~~~~~~~~~~~~~~
+===================
 
-Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin.
+Entry points (hooks) define when a plugin runs. Right now only three hooks are
+implemented. So feel free to implement a hook if it fits the behaviour of your
+plugin.
 
 Pre search hook
-```````````````
+---------------
 
 Runs BEFORE the search request. Function to implement: ``pre_search``
 
 Post search hook
-````````````````
+----------------
 
 Runs AFTER the search request. Function to implement: ``post_search``
 
 Result hook
-```````````
+-----------
 
-Runs when a new result is added to the result list. Function to implement: ``on_result``
+Runs when a new result is added to the result list. Function to implement:
+``on_result``
diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst
index e7d4baf46..a4a37a266 100644
--- a/docs/dev/quickstart.rst
+++ b/docs/dev/quickstart.rst
@@ -1,17 +1,18 @@
 .. _devquickstart:
 
+======================
 Development Quickstart
-----------------------
+======================
 
-This quickstart guide gets your environment set up with searx. Furthermore, it gives a
-short introduction to the new manage.sh script.
+This quickstart guide gets your environment set up with searx.  Furthermore, it
+gives a short introduction to the ``manage.sh`` script.
 
 How to setup your development environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=========================================
 
-First, clone the source code of searx to the desired folder. In this case the source
-is cloned to ~/myprojects/searx. Then create and activate the searx-ve
-virtualenv and install the required packages using manage.sh.
+First, clone the source code of searx to the desired folder.  In this case the
+source is cloned to ``~/myprojects/searx``.  Then create and activate the
+searx-ve virtualenv and install the required packages using manage.sh.
 
 .. code:: sh
 
@@ -24,85 +25,86 @@ virtualenv and install the required packages using manage.sh.
 
 
 How to run tests
-~~~~~~~~~~~~~~~~
+================
 
-Tests can be run using the manage.sh script.
-
-Following tests and checks are available:
+Tests can be run using the ``manage.sh`` script.  Following tests and checks are
+available:
 
 - Unit tests
-
 - Selenium tests
-
 - PEP8 validation
-
 - Unit test coverage check
 
 For example unit tests are run with the command below:
 
 .. code:: sh
 
-    ./manage.sh unit_tests
+   ./manage.sh unit_tests
 
-For further test options, please consult the help of the manage.sh script.
+For further test options, please consult the help of the ``manage.sh`` script.
 
 
 How to compile styles and javascript
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+====================================
+
+.. _less: http://lesscss.org/
+.. _NodeJS: https://nodejs.org
 
 How to build styles
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
-Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt.
+Less_ is required to build the styles of searx.  Less_ can be installed using
+either NodeJS_ or Apt.
 
 .. code:: sh
 
-    sudo apt-get install nodejs
-    sudo npm install -g less
-
+   sudo -H apt-get install nodejs
+   sudo -H npm install -g less
 
 OR
 
 .. code:: sh
 
-    sudo apt-get install node-less
+   sudo -H apt-get install node-less
 
-After satisfying the requirements styles can be build using manage.sh
+After satisfying the requirements styles can be build using ``manage.sh``
 
 .. code:: sh
 
-    ./manage.sh styles
+   ./manage.sh styles
 
 
 How to build the source of the oscar theme
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+==========================================
 
-Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first
-Node has to be installed.
+.. _grunt: https://gruntjs.com/
+
+Grunt_ must be installed in order to build the javascript sources. It depends on
+NodeJS, so first Node has to be installed.
 
 .. code:: sh
 
-    sudo apt-get install nodejs
-    sudo npm install -g grunt-cli
+   sudo -H apt-get install nodejs
+   sudo -H npm install -g grunt-cli
 
-After installing grunt, the files can be built using the following command: 
+After installing grunt, the files can be built using the following command:
 
 .. code:: sh
 
-    ./manage.sh grunt_build
-
+   ./manage.sh grunt_build
 
 
 Tips for debugging/development
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Turn on debug logging
-    Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
-    to turn on debug logging. When debug logging is enabled a stack trace appears,
-    instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting
-    ``debug: False`` to ``debug: True`` in settings.yml.
-
-2. Run ``./manage.sh tests`` before creating a PR.
-    Failing build on Travis is common because of PEP8 checks. So a new commit must be created
-    containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run
-    locally before creating a PR.
+==============================
+
+Turn on debug logging
+  Whether you are working on a new engine or trying to eliminate a bug, it is
+  always a good idea to turn on debug logging.  When debug logging is enabled a
+  stack trace appears, instead of the cryptic ``Internal Server Error``
+  message. It can be turned on by setting ``debug: False`` to ``debug: True`` in
+  :origin:`settings.yml <searx/settings.yml>`.
+
+Run ``./manage.sh tests`` before creating a PR.
+  Failing build on Travis is common because of PEP8 checks.  So a new commit
+  must be created containing these format fixes.  This phase can be skipped if
+  ``./manage.sh tests`` is run locally before creating a PR.
diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst
index ea3b0501a..158cab7c5 100644
--- a/docs/dev/search_api.rst
+++ b/docs/dev/search_api.rst
@@ -1,3 +1,4 @@
+==========
 Search API
 ==========
 
@@ -11,194 +12,101 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying.
 ``GET /search``
 
 Parameters
-~~~~~~~~~~
-
-.. code:: sh
-
-    q
-
-The search query. This string is passed to external search services.
-Thus, searx supports syntax of each search service. For example, ``site:github.com searx`` is a valid
-query for Google. However, if simply the query above is passed to any search engine which does not filter its
-results based on this syntax, you might not get the results you wanted.
-
-
-See more at :doc:`/user/search_syntax`
-
-Required.
-
-.. code:: sh
-
-    categories
-
-Comma separated list, specifies the active search categories
-
-Optional.
-
-.. code:: sh
-
-    engines
-
-Comma separated list, specifies the active search engines.
-
-Optional.
-
-.. code:: sh
-
-    lang
-
-Code of the language.
-
-Optional.
-
-Default: ``all``
-
-.. code:: sh
-
-    pageno
-
-Search page number.
-
-Optional.
-
-Default: ``1``
-
-.. code:: sh
-
-    time_range
-
-Time range of search for engines which support it. See if an engine supports time range search in the preferences page of an instance.
-
-Optional.
-
-Possible: ``day``, ``month``, ``year``
-
-.. code:: sh
-
-    format
-
-Output format of results.
-
-Optional.
-
-Possible: ``json``, ``csv``, ``rss``
-
-.. code:: sh
-
-    results_on_new_tab
-
-Open search results on new tab.
-
-Optional.
-
-Default: ``0``
-
-Possible: ``0``, ``1``
-
-.. code:: sh
-
-    image_proxy
-
-Proxy image results through searx.
-
-Optional.
-
-Default: ``False``
-
-Possible: ``True``, ``False``
-
-.. code:: sh
-
-    autocomplete
-
-Service which completes words as you type.
-
-Optional.
-
-Default: empty
-
-Possible: ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia``
-
-.. code:: sh
-
-    safesearch
-
-Filter search results of engines which support safe search. See if an engine supports safe search in the preferences page of an instance.
-
-Optional.
-
-Default: ``None``
-
-Possible: ``0``, ``1``, ``None``
-
-.. code:: sh
-
-    theme
-
-Theme of instance.
-
-Optional.
+==========
 
-Default: ``oscar``
+``q`` : required
+  The search query.  This string is passed to external search services.  Thus,
+  searx supports syntax of each search service.  For example, ``site:github.com
+  searx`` is a valid query for Google.  However, if simply the query above is
+  passed to any search engine which does not filter its results based on this
+  syntax, you might not get the results you wanted.
 
-Possible: ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette``
+  See more at :ref:`search-syntax`
 
-Please note, available themes depend on an instance. It is possible that an instance administrator deleted, created or renamed themes on his/her instance. See the available options in the preferences page of the instance.
+``categories`` : optional
+  Comma separated list, specifies the active search categories
 
-.. code:: sh
+``engines``: optional
+  Comma separated list, specifies the active search engines.
 
-    oscar-style
+``lang``: default ``all``
+  Code of the language.
 
-Style of Oscar theme. It is only parsed if the theme of an instance is ``oscar``.
+``pageno``: default ``1``
+  Search page number.
 
-Optional.
+``time_range``: optional
+  [ ``day``, ``month``, ``year`` ]
 
-Default: ``logicodev``
+  Time range of search for engines which support it.  See if an engine supports
+  time range search in the preferences page of an instance.
 
-Possible: ``pointhi``, ``logicodev``
+``format``: optional
+  [ ``json``, ``csv``, ``rss`` ]
 
-Please note, available styles depend on an instance. It is possible that an instance administrator deleted, created or renamed styles on his/her instance. See the available options in the preferences page of the instance.
+  Output format of results.
 
-.. code:: sh
+``results_on_new_tab``: default ``0``
+  [ ``0``, ``1`` ]
 
-    enabled_plugins
+  Open search results on new tab.
 
-List of enabled plugins.
+``image_proxy``: default ``False``
+  [  ``True``, ``False`` ]
 
-Optional.
+  Proxy image results through searx.
 
-Default: ``HTTPS_rewrite``, ``Self_Informations``, ``Search_on_category_select``, ``Tracker_URL_remover``
+``autocomplete``: default *empty*
+  [ ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` ]
 
-Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
+  Service which completes words as you type.
 
-.. code:: sh
+``safesearch``:  default ``None``
+  [ ``0``, ``1``, ``None`` ]
 
-    disabled_plugins
+  Filter search results of engines which support safe search.  See if an engine
+  supports safe search in the preferences page of an instance.
 
-List of disabled plugins.
+``theme``: default ``oscar``
+  [ ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` ]
 
-Optional.
+  Theme of instance.
 
-Default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``
+  Please note, available themes depend on an instance.  It is possible that an
+  instance administrator deleted, created or renamed themes on his/her instance.
+  See the available options in the preferences page of the instance.
 
-Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
+``oscar-style``: default ``logicodev``
+  [ ``pointhi``, ``logicodev`` ]
 
-.. code:: sh
+  Style of Oscar theme.  It is only parsed if the theme of an instance is
+  ``oscar``.
 
-    enabled_engines
+  Please note, available styles depend on an instance.  It is possible that an
+  instance administrator deleted, created or renamed styles on his/her
+  instance. See the available options in the preferences page of the instance.
 
-List of enabled engines.
+``enabled_plugins``: optional
+  List of enabled plugins.
 
-Optional.
+  :default: ``HTTPS_rewrite``, ``Self_Informations``,
+    ``Search_on_category_select``, ``Tracker_URL_remover``
 
-Possible:  all engines
+  :values: [ ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``,
+    ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``,
+    ``Search_on_category_select`` ]
 
-.. code:: sh
+``disabled_plugins``: optional
+  List of disabled plugins.
 
-    disabled_engines
+  :default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``
+  :values: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``,
+    ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``,
+    ``Search_on_category_select``
 
-List of disabled engines.
+``enabled_engines``: optional : *all* :origin:`engines <searx/engines>`
+  List of enabled engines.
 
-Optional.
+``disabled_engines``: optional : *all* :origin:`engines <searx/engines>`
+  List of disabled engines.
 
-Possible: all engines
diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst
index ab4dd98cb..86c4c843b 100644
--- a/docs/dev/translation.rst
+++ b/docs/dev/translation.rst
@@ -1,28 +1,36 @@
+.. _translation:
+
+===========
 Translation
 ===========
 
-Requirements
-------------
+.. _searx@transifex: https://www.transifex.com/asciimoo/searx/
+
+Translation currently takes place on `searx@transifex`_
 
- * Transifex account
+Requirements
+============
 
- * Installed CLI tool of Transifex
+* Transifex account
+* Installed CLI tool of Transifex
 
 Init Transifex project
-----------------------
+======================
 
-After installing ``transifex`` using pip, run the following command to initialize the project.
+After installing ``transifex`` using pip, run the following command to
+initialize the project.
 
-.. code:: shell
+.. code:: sh
 
-    tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/
+   tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/
 
 
-After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it into the configuration file.
+After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it
+into the configuration file.
 
 Create a configuration file for ``tx`` named ``$HOME/.tx/config``.
 
-.. code:: shell
+.. code:: ini
 
     [main]
     host = https://www.transifex.com
@@ -42,20 +50,22 @@ Then run ``tx set``:
 
 
 Update translations
--------------------
+===================
 
 To retrieve the latest translations, pull it from Transifex.
 
-.. code:: shell
+.. code:: sh
 
-    tx pull -a
+   tx pull -a
 
-Then check the new languages. If strings translated are not enough, delete those folders, because
-those should not be compiled. Call the command below to compile the ``.po`` files.
+Then check the new languages.  If strings translated are not enough, delete those
+folders, because those should not be compiled.  Call the command below to compile
+the ``.po`` files.
 
 .. code:: shell
 
-    pybabel compile -d searx/translations
+   pybabel compile -d searx/translations
 
 
-After the compilation is finished commit the ``.po`` and ``.mo`` files and create a PR.
+After the compilation is finished commit the ``.po`` and ``.mo`` files and
+create a PR.