From 845a0b678d0c94a68d0ec333aeaa7f7e6b7a18e8 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Tue, 28 May 2024 10:30:36 +0200
Subject: [PATCH] [doc] add 'hostnames' plugin to the online documentation

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/src/searx.plugins.hostnames.rst |  9 ++++++
 searx/plugins/hostnames.py           | 47 +++++++++++++++++++++++++++-
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/searx.plugins.hostnames.rst

diff --git a/docs/src/searx.plugins.hostnames.rst b/docs/src/searx.plugins.hostnames.rst
new file mode 100644
index 000000000..5d0365536
--- /dev/null
+++ b/docs/src/searx.plugins.hostnames.rst
@@ -0,0 +1,9 @@
+.. _hostnames plugin:
+
+================
+Hostnames plugin
+================
+
+.. automodule:: searx.plugins.hostnames
+  :members:
+
diff --git a/searx/plugins/hostnames.py b/searx/plugins/hostnames.py
index 6ab6147dd..0fafcbb6d 100644
--- a/searx/plugins/hostnames.py
+++ b/searx/plugins/hostnames.py
@@ -1,5 +1,50 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
-# pylint: disable=missing-module-docstring, too-many-branches
+# pylint: disable=too-many-branches
+"""In addition to rewriting/replace reslut URLs, the *hoostnames* plugin offers
+other features.
+
+- ``hostnames.replace``: A mapping of regular expressions to hostnames to be
+  replaced by other hostnames.
+
+- ``hostnames.remove``: A list of regular expressions of the hostnames whose
+  results should be taken from the results list.
+
+- ``hostnames.high_priority``: A list of regular expressions for hostnames whose
+  result should be given higher priority. The results from these hosts are
+  arranged higher in the results list.
+
+- ``hostnames.lower_priority``: A list of regular expressions for hostnames
+  whose result should be given lower priority. The results from these hosts are
+  arranged lower in the results list.
+
+Alternatively, a file name can also be specified for the mappings or lists:
+
+.. code:: yaml
+
+   hostnames:
+     replace: 'rewrite-hosts.yml'
+     remove:
+       - '(.*\\.)?facebook.com$'
+       ...
+     low_priority:
+       - '(.*\\.)?google(\\..*)?$'
+       ...
+     high_priority:
+       - '(.*\\.)?wikipedia.org$'
+       ...
+
+The ``rewrite-hosts.yml`` from the example above must be in the folder in which
+the ``settings.yml`` file is already located (``/etc/searxng``). The file then
+only contains the lists or the mapping tables without further information on the
+namespaces.  In the example above, this would be a mapping table that looks
+something like this:
+
+.. code:: yaml
+
+   '(.*\\.)?youtube\\.com$': 'invidious.example.com'
+   '(.*\\.)?youtu\\.be$': 'invidious.example.com'
+
+"""
 
 import re
 from urllib.parse import urlunparse, urlparse