Merge pull request #996 from return42/fix-settings-doc

[docs] improve settings.yml documentation (admin/engines/settings)

docs/admin/engines/settings.rst

@@ -37,10 +37,10 @@ see how you can simplify your *user defined* ``settings.yml``.
 Global Settings
 ===============
 
-.. _settings global brand:
+.. _settings brand:
 
 ``brand:``
-------------
+----------
 
 .. code:: yaml
 
@@ -62,7 +62,7 @@ Global Settings
 ``wiki_url`` :
   Link to your wiki (or ``false``)
 
-.. _settings global general:
+.. _settings general:
 
 ``general:``
 ------------
@@ -85,7 +85,60 @@ Global Settings
   Enabled by default. Record various anonymous metrics availabled at ``/stats``,
   ``/stats/errors`` and ``/preferences``.
 
-.. _settings global server:
+.. _settings search:
+
+``search:``
+-----------
+
+.. code:: yaml
+
+   search:
+     safe_search: 0
+     autocomplete: ""
+     default_lang: ""
+     ban_time_on_fail: 5
+     max_ban_time_on_fail: 120
+     formats:
+       - html
+
+``safe_search``:
+  Filter results.
+
+  - ``0``: None
+  - ``1``: Moderate
+  - ``2``: Strict
+
+``autocomplete``:
+  Existing autocomplete backends, leave blank to turn it off.
+
+  - ``dbpedia``
+  - ``duckduckgo``
+  - ``google``
+  - ``startpage``
+  - ``swisscows``
+  - ``qwant``
+  - ``wikipedia``
+
+``default_lang``:
+  Default search language - leave blank to detect from browser information or
+  use codes from :origin:`searx/languages.py`.
+
+``ban_time_on_fail``:
+  Ban time in seconds after engine errors.
+
+``max_ban_time_on_fail``:
+  Max ban time in seconds after engine errors.
+
+``formats``:
+  Result formats available from web, remove format to deny access (use lower
+  case).
+
+  - ``html``
+  - ``csv``
+  - ``json``
+  - ``rss``
+
+.. _settings server:
 
 ``server:``
 -----------
@@ -98,8 +151,6 @@ Global Settings
        bind_address: "127.0.0.1"      # address to listen on
        secret_key: "ultrasecretkey"   # change this!
        image_proxy: false             # proxying image results through SearXNG
-       default_locale: ""             # default interface locale
-       default_theme: oscar           # ui theme
        default_http_headers:
          X-Content-Type-Options : nosniff
          X-XSS-Protection : 1; mode=block
@@ -128,6 +179,26 @@ Global Settings
 ``image_proxy`` :
   Allow your instance of SearXNG of being able to proxy images.  Uses memory space.
 
+.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+
+``default_http_headers``:
+  Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
+
+
+.. _settings ui:
+
+``ui:``
+-------
+
+.. code:: yaml
+
+   ui:
+     default_locale: ""
+     query_in_title: false
+     default_theme: simple
+     theme_args:
+       simple_style: auto
+
 ``default_locale`` :
   SearXNG interface language.  If blank, the locale is detected by using the
   browser language.  If it doesn't work, or you are deploying a language
@@ -137,10 +208,15 @@ Global Settings
 ``default_theme`` :
   Name of the theme you want to use by default on your SearXNG instance.
 
-.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+``theme_args.simple_style``:
+  Style of simple theme: ``auto``, ``light``, ``dark``
 
-``default_http_headers``:
+``query_in_title``:
-  Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
+  When true, the result page's titles contains the query it decreases the
+  privacy, since the browser can records the page titles.
+
+``results_on_new_tab``:
+  Open result links in a new tab by default.
 
 
 .. _settings redis:
@@ -374,8 +450,9 @@ engine is shown.  Most of the options have a default value or even are optional.
 ``network``: optional
   Use the network configuration from another engine.
   In addition, there are two default networks:
-  * ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses)
+
-  * ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses)
+  - ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses)
+  - ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses)
 
 .. note::
 

docs/dev/makefile.rst

@@ -87,7 +87,7 @@ the :origin:`setup.py` file, you have to call :ref:`make clean`.
 =================
 
 Rebuild instance's environment with the modified settings from the
-:ref:`settings global brand` and :ref:`settings global server` section of your
+:ref:`settings brand` and :ref:`settings server` section of your
 :ref:`settings.yml <settings location>`.
 
 We have all SearXNG setups are centralized in the :ref:`settings.yml` file.
@@ -107,10 +107,10 @@ The ``make buildenv`` target will update the *build environment* in:
 Tasks running outside of an *installed instance*, need the following settings
 from the YAML configuration:
 
-- ``SEARXNG_URL`` from :ref:`server.base_url <settings global server>` (aka
+- ``SEARXNG_URL`` from :ref:`server.base_url <settings  server>` (aka
   ``PUBLIC_URL``)
-- ``SEARXNG_BIND_ADDRESS`` from :ref:`server.bind_address <settings global server>`
+- ``SEARXNG_BIND_ADDRESS`` from :ref:`server.bind_address <settings server>`
-- ``SEARXNG_PORT`` from :ref:`server.port <settings global server>`
+- ``SEARXNG_PORT`` from :ref:`server.port <settings server>`
 
 .. _make node.env:
 

searx/settings.yml

@@ -21,13 +21,6 @@ search:
   # Default search language - leave blank to detect from browser information or
   # use codes from 'languages.py'
   default_lang: ""
-  # Available languages
-  # languages:
-  #  - all
-  #  - es
-  #  - de
-  #  - it-IT
-  #  - en-GB
   # ban time in seconds after engine errors
   ban_time_on_fail: 5
   # max ban time in seconds after engine errors