[fix] various issues in the documentation

Closes: https://github.com/searxng/searxng/issues/4370
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

13 files changed, 38 insertions, 22 deletions

diff --git a/docs/admin/settings/index.rst b/docs/admin/settings/index.rst
index d1f808f3d..eb0e07a53 100644
--- a/docs/admin/settings/index.rst
+++ b/docs/admin/settings/index.rst
@@ -13,7 +13,7 @@ Settings
    :maxdepth: 2
 
    settings
-   settings_engine
+   settings_engines
    settings_brand
    settings_general
    settings_search
diff --git a/docs/admin/settings/settings_engine.rst b/docs/admin/settings/settings_engines.rst
index 454fcd241..944972143 100644
--- a/docs/admin/settings/settings_engine.rst
+++ b/docs/admin/settings/settings_engines.rst
@@ -1,14 +1,30 @@
-.. _settings engine:
+.. _settings engines:
 
-===========
-``engine:``
-===========
+============
+``engines:``
+============
 
 .. sidebar:: Further reading ..
 
    - :ref:`configured engines`
    - :ref:`engines-dev`
 
+
+In the section ``engines:`` is a list of the engines that are to be made
+available in the instance.  Each list entry is in turn a key/value mapping.
+
+.. code:: yaml
+
+   engines:
+
+     - name: dummy.online
+       engine: dummy
+       ..
+     - name: dummy.offline
+       engine: dummy-offline
+       ..
+     ..
+
 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.
 
@@ -19,7 +35,7 @@ engine is shown.  Most of the options have a default value or even are optional.
 
 .. code:: yaml
 
-   - name: example engine
+   - name: example
      engine: example
      shortcut: demo
      base_url: 'https://{language}.example.com/'
diff --git a/docs/admin/settings/settings_outgoing.rst b/docs/admin/settings/settings_outgoing.rst
index 7d49ab789..1896698ce 100644
--- a/docs/admin/settings/settings_outgoing.rst
+++ b/docs/admin/settings/settings_outgoing.rst
@@ -43,7 +43,7 @@ Communication with search engines.
   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 SearXNG reactivity (the result page may take the time specified in the
-  timeout to load).  Can be override by ``timeout`` in the :ref:`settings engine`.
+  timeout to load).  Can be override by ``timeout`` in the :ref:`settings engines`.
 
 ``useragent_suffix`` :
   Suffix to the user-agent SearXNG uses to send requests to others engines.  If an
@@ -105,6 +105,6 @@ Communication with search engines.
 
 ``using_tor_proxy`` :
   Using tor proxy (``true``) or not (``false``) for all engines.  The default is
-  ``false`` and can be overwritten in the :ref:`settings engine`
+  ``false`` and can be overwritten in the :ref:`settings engines`
 
 
diff --git a/docs/conf.py b/docs/conf.py
index aeb62e337..23eca3202 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -143,10 +143,10 @@ suppress_warnings = ['myst.domains']
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "babel" : ("https://babel.readthedocs.io/en/latest/", None),
-    "flask": ("https://flask.palletsprojects.com/", None),
+    "flask": ("https://flask.palletsprojects.com/en/stable/", None),
     "flask_babel": ("https://python-babel.github.io/flask-babel/", None),
-    # "werkzeug": ("https://werkzeug.palletsprojects.com/", None),
-    "jinja": ("https://jinja.palletsprojects.com/", None),
+    "werkzeug": ("https://werkzeug.palletsprojects.com/en/stable/", None),
+    "jinja": ("https://jinja.palletsprojects.com/en/stable/", None),
     "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
     "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
     "redis": ('https://redis.readthedocs.io/en/stable/', None),
diff --git a/docs/dev/engines/engine_overview.rst b/docs/dev/engines/engine_overview.rst
index 4aeb5b624..145773007 100644
--- a/docs/dev/engines/engine_overview.rst
+++ b/docs/dev/engines/engine_overview.rst
@@ -14,7 +14,7 @@ Engine Overview
 .. sidebar:: Further reading ..
 
    - :ref:`configured engines`
-   - :ref:`settings engine`
+   - :ref:`settings engines`
 
 SearXNG is a metasearch-engine_, so it uses different search engines to provide
 better results.
@@ -63,7 +63,7 @@ Engine File
 Engine ``settings.yml``
 -----------------------
 
-For a more  detailed description, see :ref:`settings engine` in the :ref:`settings.yml`.
+For a more  detailed description, see :ref:`settings engines` in the :ref:`settings.yml`.
 
 .. table:: Common options in the engine setup (``settings.yml``)
    :width: 100%
diff --git a/docs/user/configured_engines.rst b/docs/user/configured_engines.rst
index c32a264ed..00eb60272 100644
--- a/docs/user/configured_engines.rst
+++ b/docs/user/configured_engines.rst
@@ -8,7 +8,7 @@ Configured Engines
 
    - :ref:`settings categories_as_tabs`
    - :ref:`engines-dev`
-   - :ref:`settings engine`
+   - :ref:`settings engines`
    - :ref:`general engine configuration`
 
 .. jinja:: searx
diff --git a/searx/engines/gitea.py b/searx/engines/gitea.py
index 446d84472..ff6f95c83 100644
--- a/searx/engines/gitea.py
+++ b/searx/engines/gitea.py
@@ -30,7 +30,7 @@ Optional settings are:
     shortcut: forgejo
 
 If you would like to use additional instances, just configure new engines in the
-:ref:`settings <settings engine>` and set the ``base_url``.
+:ref:`settings <settings engines>` and set the ``base_url``.
 
 
 Implementation
diff --git a/searx/engines/json_engine.py b/searx/engines/json_engine.py
index 1906f9d9e..a243d5c85 100644
--- a/searx/engines/json_engine.py
+++ b/searx/engines/json_engine.py
@@ -54,7 +54,7 @@ Example
 =======
 
 Here is a simple example of a JSON engine configure in the :ref:`settings
-engine` section, further read :ref:`engines-dev`.
+engines` section, further read :ref:`engines-dev`.
 
 .. code:: yaml
 
@@ -384,7 +384,7 @@ def extract_response_info(result):
 
 
 def response(resp):
-    '''Scrap *results* from the response (see :ref:`engine results`).'''
+    '''Scrap *results* from the response (see :ref:`result types`).'''
     results = []
 
     if no_result_for_http_status and resp.status_code in no_result_for_http_status:
diff --git a/searx/engines/lemmy.py b/searx/engines/lemmy.py
index 1845431d7..d301de4c6 100644
--- a/searx/engines/lemmy.py
+++ b/searx/engines/lemmy.py
@@ -16,7 +16,7 @@ The engine has the following additional settings:
 - :py:obj:`lemmy_type`
 
 This implementation is used by different lemmy engines in the :ref:`settings.yml
-<settings engine>`:
+<settings engines>`:
 
 .. code:: yaml
 
diff --git a/searx/engines/qwant.py b/searx/engines/qwant.py
index 7ad6cf58a..8ab02b256 100644
--- a/searx/engines/qwant.py
+++ b/searx/engines/qwant.py
@@ -17,7 +17,7 @@ The engine has the following additional settings:
 - :py:obj:`qwant_categ`
 
 This implementation is used by different qwant engines in the :ref:`settings.yml
-<settings engine>`:
+<settings engines>`:
 
 .. code:: yaml
 
diff --git a/searx/engines/seekr.py b/searx/engines/seekr.py
index 967eef86d..3bd739964 100644
--- a/searx/engines/seekr.py
+++ b/searx/engines/seekr.py
@@ -13,7 +13,7 @@ The engine has the following additional settings:
 - :py:obj:`api_key`
 
 This implementation is used by seekr engines in the :ref:`settings.yml
-<settings engine>`:
+<settings engines>`:
 
 .. code:: yaml
 
diff --git a/searx/engines/xpath.py b/searx/engines/xpath.py
index db892d392..b1bef923d 100644
--- a/searx/engines/xpath.py
+++ b/searx/engines/xpath.py
@@ -52,7 +52,7 @@ Example
 =======
 
 Here is a simple example of a XPath engine configured in the :ref:`settings
-engine` section, further read :ref:`engines-dev`.
+engines` section, further read :ref:`engines-dev`.
 
 .. code:: yaml
 
diff --git a/searx/utils.py b/searx/utils.py
index c7a579451..f342c2803 100644
--- a/searx/utils.py
+++ b/searx/utils.py
@@ -473,7 +473,7 @@ def ecma_unescape(string: str) -> str:
 def remove_pua_from_str(string):
     """Removes unicode's "PRIVATE USE CHARACTER"s (PUA_) from a string.
 
-    _PUA: https://en.wikipedia.org/wiki/Private_Use_Areas
+    .. _PUA: https://en.wikipedia.org/wiki/Private_Use_Areas
     """
     pua_ranges = ((0xE000, 0xF8FF), (0xF0000, 0xFFFFD), (0x100000, 0x10FFFD))
     s = []