docs(admin): moved settings description from wiki to docs

Move wiki entry https://github.com/asciimoo/searx/wiki/settings.yml
into admin section of the docs (#1785).

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

docs/admin/engines.rst

@@ -6,8 +6,7 @@ Engines
 
 .. sidebar:: Further reading ..
 
-   - :ref:`engines generic`
+   - :ref:`settings engine`
-   - :ref:`configured engines`
    - :ref:`engine settings`
    - :ref:`engine file`
 

docs/admin/index.rst

@@ -6,6 +6,7 @@ Administrator documentation
    :maxdepth: 1
 
    installation
+   settings
    api
    architecture
    filtron

docs/admin/settings.rst

@@ -0,0 +1,181 @@
+.. _settings.yml:
+
+================
+``settings.yml``
+================
+
+.. sidebar:: Further reading ..
+
+   - :ref:`search API`
+
+This page describe the options possibilities of the settings.yml file.
+
+.. _settings global:
+
+Global Settings
+===============
+
+.. code:: yaml
+
+   server:
+       port : 8888
+       secret_key : "ultrasecretkey" # change this!
+       debug : False                 # debug mode, only for development
+       request_timeout : 2.0         # seconds
+       base_url : False              # set custom base_url (or False)
+       themes_path : ""              # custom ui themes path
+       default_theme : oscar         # ui theme
+       useragent_suffix : ""         # suffix of searx_useragent, could contain
+                                     # informations like admins email address
+       image_proxy : False           # proxying image results through searx
+       default_locale : ""           # default interface locale
+
+   # uncomment below section if you want to use a proxy
+
+   #outgoing_proxies :
+   #    http : http://127.0.0.1:8080
+   #    https: http://127.0.0.1:8080
+
+   # uncomment below section only if you have more than one network interface
+   # which can be the source of outgoing search requests
+
+   #source_ips:
+   #  - 1.1.1.1
+   #  - 1.1.1.2
+
+   locales:
+       en : English
+       de : Deutsch
+       he : Hebrew
+       hu : Magyar
+       fr : Français
+       es : Español
+       it : Italiano
+       nl : Nederlands
+       ja : 日本語 (Japanese)
+       tr : Türkçe
+       ru : Russian
+       ro : Romanian
+
+
+``port`` :
+  Port number of the searx web application if you run it directly using ``python
+  searx/webapp.py``.  Doesn't apply to searx running on Apache or Nginx.
+
+``secret_key`` :
+  Used for cryptography purpose.
+
+``debug`` :
+  Allow a more detailed log if you run searx directly. Display *detailed* error
+  messages in the browser too, so this must be deactivated in production.
+
+``request_timeout`` :
+  Global timeout of the requests made to others engines in seconds. A bigger
+  timeout will allow to wait for answers from slow engines, but in consequence
+  will slow searx reactivity (the result page may take the time specified in the
+  timeout to load)
+
+``base_url`` :
+  The base URL where searx is deployed.  Used to create correct inbound links.
+
+``themes_path`` :
+  Path to where the themes are located.  If you didn't develop anything, leave it
+  blank.
+
+``default_theme`` :
+  Name of the theme you want to use by default on you searx instance.
+
+``useragent_suffix`` :
+  Suffix to the user-agent searx uses to send requests to others engines.  If an
+  engine wish to block you, a contact info here may be useful to avoid that.
+
+``image_proxy`` :
+  Allow your instance of searx of being able to proxy images.  Uses memory space.
+
+``default_locale`` :
+  Aearx interface language.  If blank, the locale is detected by using the
+  browser language.  If it doesn't work, or you are deploying a language
+  specific instance of searx, a locale can be defined using an ISO language
+  code, like ``fr``, ``en``, ``de``.
+
+.. _requests proxies: http://docs.python-requests.org/en/latest/user/advanced/#proxies
+.. _PR SOCKS support: https://github.com/kennethreitz/requests/pull/478
+
+``outgoing_proxies`` :
+  Define a proxy you wish to use, see `requests proxies`_.  SOCKS proxies are
+  not supported / see `PR SOCKS support`.
+
+``source_ips`` :
+  If you use multiple nework interfaces, define from which IP the requests must
+  be made.
+
+``locales`` :
+  Locales codes and their names.  Available translations of searx interface.
+
+
+.. _settings engine:
+
+Engine settings
+===============
+
+.. sidebar:: Further reading ..
+
+   - :ref:`engines-dev`
+
+.. code:: yaml
+
+   - name : bing
+     engine : bing
+     shortcut : bi
+     base_url : 'https://{language}.wikipedia.org/'
+     categories : general
+     timeout : 3.0
+     api_key : 'apikey'
+     disabled : True
+     language : en_US
+
+``name`` :
+  Name that will be used accross searx to define this engine.  In settings, on
+  the result page...
+
+``engine`` :
+  Name of the python file used to handle requests and responses to and from this
+  search engine.
+
+``shortcut`` :
+  Code used to execute bang requests (in this case using ``!bi`` or ``?bi``)
+
+``base_url`` : optional
+  Part of the URL that should be stable accross every request.  Can be useful to
+  use multiple sites using only one engine, or updating the site URL without
+  touching at the code.
+
+``categories`` : optional
+  Define in which categories this engine will be active.  Most of the time, it is
+  defined in the code of the engine, but in a few cases it is useful, like when
+  describing multiple search engine using the same code.
+
+``timeout`` : optional
+  Timeout of the search with the current search engine.  **Be careful, it will
+  modify the global timeout of searx.**
+
+``api_key`` : optional
+  In a few cases, using an API needs the use of a secret key.  How to obtain them
+  is described in the file.
+
+``disabled`` : optional
+  To disable by default the engine, but not deleting it. It will allow the user
+  to manually activate it in the settings.
+
+``language`` : optional
+  If you want to use another language for a specific engine, you can define it
+  by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
+  ``de_DE``.
+
+``weigth`` : default ``1``
+  Weighting of the results of this engine.
+
+.. note::
+
+   A few more options are possible, but they are pretty specific to some
+   engines, and so won't be described here.

docs/dev/search_api.rst

@@ -1,3 +1,5 @@
+.. _search API:
+
 ==========
 Search API
 ==========
@@ -16,10 +18,9 @@ Parameters
 
 .. sidebar:: Further reading ..
 
+   - :ref:`engines-dev`
+   - :ref:`settings.yml`
    - :ref:`engines generic`
-   - :ref:`configured engines`
-   - :ref:`engine settings`
-   - :ref:`engine file`
 
 ``q`` : required
   The search query.  This string is passed to external search services.  Thus,