[docs] revision of the article "settings.yml"

This patch is a marginal revision of the article "settings.yml", most changes are from normalizing the YAML syntax. Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
2021-06-03 18:56:39 +02:00 · 2021-06-03 18:56:39 +02:00 · c647c8b7a5
parent 5caebb379f
commit c647c8b7a5
1 changed files with 125 additions and 101 deletions
--- a/docs/admin/settings.rst
+++ b/docs/admin/settings.rst
@ -22,13 +22,14 @@ file.
 settings.yml location
 =====================

-First, searx will try to load settings.yml from these locations:
+The initial ``settings.yml`` we be load from these locations:

 1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
 2. ``/etc/searx/settings.yml``

 If these files don't exist (or are empty or can't be read), searx uses the
-:origin:`searx/settings.yml` file.
+:origin:`searx/settings.yml` file.  Read :ref:`settings use_default_settings` to
+see how you can simplify your *user defined* ``settings.yml``.


 .. _settings global:
@ -42,9 +43,11 @@ Global Settings
 .. code:: yaml

   general:
-       debug : False # Debug mode, only for development
+     debug: false               # Debug mode, only for development
     instance_name:  "searxng"  # displayed name
-       contact_url: False # mailto:contact@example.com
+     contact_url: false         # mailto:contact@example.com
+
+.. code:: yaml

   brand:
     git_url: https://github.com/searxng/searxng
@ -68,10 +71,10 @@ Global Settings
  If you host your own documentation, change this URL.

 ``wiki_url``:
-  Link to your wiki (or ``False``)
+  Link to your wiki (or ``false``)

 ``twitter_url``:
-  Link to your tweets (or ``False``)
+  Link to your tweets (or ``false``)


 ``server:``
@ -83,8 +86,8 @@ Global Settings
       port: 8888
       bind_address: "127.0.0.1"      # address to listen on
       secret_key: "ultrasecretkey"   # change this!
-       base_url : False                # set custom base_url (or False)
-       image_proxy : False             # proxying image results through searx
+       base_url: false                # set custom base_url (or false)
+       image_proxy: false             # proxying image results through searx
       default_locale: ""             # default interface locale
       default_theme: oscar           # ui theme
       default_http_headers:
@ -125,15 +128,19 @@ Global Settings
 ``outgoing:``
 -------------

+Communication with search engines.
+
 .. code:: yaml

-   outgoing: # communication with search engines
+   outgoing:
     request_timeout: 2.0       # default timeout in seconds, can be override by engine
-       # max_request_timeout: 10.0  # the maximum timeout in seconds
+     max_request_timeout: 10.0  # the maximum timeout in seconds
     useragent_suffix: ""       # informations like an email address to the administrator
-       pool_connections : 100       # Maximum number of allowable connections, or None for no limits. The default is 100.
-       pool_maxsize : 10            # Number of allowable keep-alive connections, or None to always allow. The default is 10.
-       enable_http2: True           # See https://www.python-httpx.org/http2/
+     pool_connections: 100      # Maximum number of allowable connections, or null
+                                # for no limits. The default is 100.
+     pool_maxsize: 10           # Number of allowable keep-alive connections, or null
+                                # to always allow. The default is 10.
+     enable_http2: true         # See https://www.python-httpx.org/http2/
     # uncomment below section if you want to use a proxy
     # proxies:
     #   all://:
@ -180,8 +187,8 @@ Global Settings
  * ``[ 192.168.0.1, fe80::/126 ]``

 ``retries`` :
-  Number of retry in case of an HTTP error.
-  On each retry, searx uses an different proxy and source ip.
+  Number of retry in case of an HTTP error.  On each retry, searx uses an
+  different proxy and source ip.

 ``retry_on_http_error`` :
  Retry request on some HTTP status code.
@ -193,7 +200,7 @@ Global Settings
  * ``[403, 429]``: on HTTP status code 403 and 429.

 ``enable_http2`` :
-  Enable by default. Set to ``False`` to disable HTTP/2.
+  Enable by default. Set to ``false`` to disable HTTP/2.

 ``max_redirects`` :
  30 by default. Maximum redirect before it is an error.
@ -232,33 +239,46 @@ Engine settings
   - :ref:`general engine settings`
   - :ref:`engines-dev`

+In the code example below a *full fledged* example of a YAML setup from a dummy
+engine is shown.  Most of the options have a default value or even are optional.
+
 .. code:: yaml

-   - name : bing
-     engine : bing
-     shortcut : bi
-     base_url : 'https://{language}.wikipedia.org/'
+   - name: example engine
+     engine: example
+     shortcut: demo
+     base_url: 'https://{language}.example.com/'
     categories: general
     timeout: 3.0
     api_key: 'apikey'
-     disabled : True
+     disabled: false
     language: en_US
-     #enable_http: False
-     #enable_http2: False
-     #retries: 1
-     #retry_on_http_error: True # or 403 or [404, 429]
-     #max_connections: 100
-     #max_keepalive_connections: 10
-     #keepalive_expiry: 5.0
-     #proxies:
-     #    http:
-     #        - http://proxy1:8080
-     #        - http://proxy2:8080
-     #    https:
-     #        - http://proxy1:8080
-     #        - http://proxy2:8080
-     #        - socks5://user:password@proxy3:1080
-     #        - socks5h://user:password@proxy4:1080
+     tokens: [ 'my-secret-token' ]
+     weigth: 1
+     display_error_messages: true
+     about:
+        website: https://example.com
+        wikidata_id: Q306656
+        official_api_documentation: https://example.com/api-doc
+        use_official_api: true
+        require_api_key: true
+        results: HTML
+     enable_http: false
+     enable_http2: false
+     retries: 1
+     retry_on_http_error: true # or 403 or [404, 429]
+     max_connections: 100
+     max_keepalive_connections: 10
+     keepalive_expiry: 5.0
+     proxies:
+       http:
+         - http://proxy1:8080
+         - http://proxy2:8080
+       https:
+         - http://proxy1:8080
+         - http://proxy2:8080
+         - socks5://user:password@proxy3:1080
+         - socks5h://user:password@proxy4:1080

 ``name`` :
  Name that will be used across searx to define this engine.  In settings, on
@ -298,10 +318,14 @@ Engine settings
  by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
  ``de_DE``.

+``tokens`` : optional
+  A list of secret tokens to make this engine *private*, more details see
+  :ref:`private engines`.
+
 ``weigth`` : default ``1``
  Weighting of the results of this engine.

-``display_error_messages`` : default ``True``
+``display_error_messages`` : default ``true``
  When an engine returns an error, the message is displayed on the user interface.

 ``network``: optional
@ -321,7 +345,7 @@ Engine settings
 use_default_settings
 ====================

-.. sidebar:: ``use_default_settings: True``
+.. sidebar:: ``use_default_settings: true``

   - :ref:`settings location`
   - :ref:`use_default_settings.yml`
@ -330,7 +354,7 @@ use_default_settings
 The user defined ``settings.yml`` is loaded from the :ref:`settings location`
 and can relied on the default configuration :origin:`searx/settings.yml` using:

- ``use_default_settings: True``
+ ``use_default_settings: true``

 ``server:``
  In the following example, the actual settings are the default settings defined
@ -339,22 +363,22 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:

  .. code-block:: yaml

-    use_default_settings: True
+    use_default_settings: true
    server:
-        secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+        secret_key: "ultrasecretkey"   # change this!
        bind_address: "0.0.0.0"

 ``engines:``
-  With ``use_default_settings: True``, each settings can be override in a
+  With ``use_default_settings: true``, each settings can be override in a
  similar way, the ``engines`` section is merged according to the engine
  ``name``.  In this example, searx will load all the engine and the arch linux
  wiki engine has a :ref:`token <private engines>`:

  .. code-block:: yaml

-    use_default_settings: True
+    use_default_settings: true
    server:
-        secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: arch linux wiki
        tokens: ['$ecretValue']
@ -371,7 +395,7 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
        remove:
          - google
    server:
-        secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: arch linux wiki
        tokens: ['$ecretValue']
@ -388,7 +412,7 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
          - google
          - duckduckgo
    server:
-        secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
+      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: google
        tokens: ['$ecretValue']