From 7aa95d2d52501b01d8c289c82ca79475cbf0da34 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Fri, 28 Jul 2023 20:16:18 +0200
Subject: [PATCH] [doc] engine piped: add documentation to
 docs/dev/engines/online/

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/dev/engines/online/piped.rst | 13 +++++++++++
 searx/engines/piped.py            | 38 +++++++++++++++++++++++++------
 searx/settings.yml                |  2 +-
 3 files changed, 45 insertions(+), 8 deletions(-)
 create mode 100644 docs/dev/engines/online/piped.rst

diff --git a/docs/dev/engines/online/piped.rst b/docs/dev/engines/online/piped.rst
new file mode 100644
index 000000000..822981056
--- /dev/null
+++ b/docs/dev/engines/online/piped.rst
@@ -0,0 +1,13 @@
+.. _piped engine:
+
+=====
+Piped
+=====
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.piped
+  :members:
diff --git a/searx/engines/piped.py b/searx/engines/piped.py
index 3a721f9db..c34ab198f 100644
--- a/searx/engines/piped.py
+++ b/searx/engines/piped.py
@@ -1,8 +1,18 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # lint: pylint
-"""Piped (Videos)
+"""An alternative privacy-friendly YouTube frontend which is efficient by
+design.  `Piped’s architecture`_ consists of 3 components:
+
+- :py:obj:`backend <backend_url>`
+- :py:obj:`frontend <frontend_url>`
+- proxy
+
+.. _Piped’s architecture: https://docs.piped.video/docs/architecture/
+
 """
 
+from __future__ import annotations
+
 import time
 import random
 from urllib.parse import urlencode
@@ -23,24 +33,38 @@ categories = ["videos", "music"]
 paging = False
 
 # search-url
-backend_url = "https://pipedapi.kavin.rocks"
-frontend_url = "https://piped.video"
+backend_url: list|str = "https://pipedapi.kavin.rocks"
+"""Piped-Backend_: The core component behind Piped.  The value is an URL or a
+list of URLs.  In the latter case instance will be selected randomly.  For a
+complete list of offical instances see Piped-Instances (`JSON
+<https://piped-instances.kavin.rocks/>`__)
 
+.. _Piped-Instances: https://github.com/TeamPiped/Piped/wiki/Instances
+.. _Piped-Backend: https://github.com/TeamPiped/Piped-Backend
+
+"""
+
+frontend_url: str = "https://piped.video"
+"""Piped-Frontend_: URL to use as link and for embeds.
+
+.. _Piped-Frontend: https://github.com/TeamPiped/Piped
+"""
+
+content_filter = 'videos'
+"""Content filter ``music_albums`` or ``videos``"""
 
-# do search-request
 def request(query, params):
     if isinstance(backend_url, list):
         base_url = random.choice(backend_url)
     else:
         base_url = backend_url
 
-    search_url = base_url + "/search?{query}&filter=videos"
-    params["url"] = search_url.format(query=urlencode({'q': query}))
+    query = urlencode({'q': query})
+    params["url"] = base_url + f"/search?{query}&filter={content_filter}"
 
     return params
 
 
-# get response from search-request
 def response(resp):
     results = []
 
diff --git a/searx/settings.yml b/searx/settings.yml
index d2847343a..4d5992354 100644
--- a/searx/settings.yml
+++ b/searx/settings.yml
@@ -1142,7 +1142,7 @@ engines:
       - https://pipedapi.kavin.rocks
       - https://pipedapi-libre.kavin.rocks
       - https://pipedapi.adminforge.de
-    # Url to use as link, and for embeds
+    # URL to use as link and for embeds
     frontend_url: https://srv.piped.video
     shortcut: ppd
     timeout: 3.0