From 1d0abb7157a24fd2c43afe30a35527cba3d6967a Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Sat, 5 Aug 2023 21:33:30 +0200
Subject: [PATCH] [doc] engine bt4g: add documentation to
 docs/dev/engines/online/

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/dev/engines/index.rst       |  8 +++--
 docs/dev/engines/online/bt4g.rst | 14 +++++++++
 searx/engines/bt4g.py            | 52 +++++++++++++++++++++++++++++---
 3 files changed, 68 insertions(+), 6 deletions(-)
 create mode 100644 docs/dev/engines/online/bt4g.rst

diff --git a/docs/dev/engines/index.rst b/docs/dev/engines/index.rst
index daa12f202..b5c3184e0 100644
--- a/docs/dev/engines/index.rst
+++ b/docs/dev/engines/index.rst
@@ -4,10 +4,14 @@
 Engine Implementations
 ======================
 
-Framework Components
-====================
+.. contents::
+   :depth: 2
+   :local:
+   :backlinks: entry
+
 
 .. toctree::
+   :caption: Framework Components
    :maxdepth: 2
 
    enginelib
diff --git a/docs/dev/engines/online/bt4g.rst b/docs/dev/engines/online/bt4g.rst
new file mode 100644
index 000000000..980665204
--- /dev/null
+++ b/docs/dev/engines/online/bt4g.rst
@@ -0,0 +1,14 @@
+.. _bt4g engine:
+
+====
+BT4G
+====
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+.. automodule:: searx.engines.bt4g
+  :members:
+
diff --git a/searx/engines/bt4g.py b/searx/engines/bt4g.py
index a952e618d..34717aeaf 100644
--- a/searx/engines/bt4g.py
+++ b/searx/engines/bt4g.py
@@ -1,7 +1,40 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # lint: pylint
-"""
- BT4G (Videos, Music, Files)
+"""BT4G_ (bt4g.com) is not a tracker and doesn't store any content and only
+collects torrent metadata (such as file names and file sizes) and a magnet link
+(torrent identifier).
+
+This engine does not parse the HTML page because there is an API in XML (RSS).
+The RSS feed provides fewer data like amount of seeders/leechers and the files
+in the torrent file.  It's a tradeoff for a "stable" engine as the XML from RSS
+content will change way less than the HTML page.
+
+.. _BT4G: https://bt4g.com/
+
+Configuration
+=============
+
+The engine has the following additional settings:
+
+- :py:obj:`bt4g_order_by`
+- :py:obj:`bt4g_category`
+
+With this options a SearXNG maintainer is able to configure **additional**
+engines for specific torrent searches.  For example a engine to search only for
+Movies and sort the result list by the count of seeders.
+
+.. code:: yaml
+
+  - name: bt4g.movie
+    engine: bt4g
+    shortcut: bt4gv
+    categories: video
+    bt4g_order_by: seeders
+    bt4g_category: 'movie'
+
+Implementations
+===============
+
 """
 
 import re
@@ -28,8 +61,19 @@ time_range_support = True
 # search-url
 url = 'https://bt4gprx.com'
 search_url = url + '/search?q={search_term}&orderby={order_by}&category={category}&p={pageno}&page=rss'
-bt4g_order_by = 'relevance'  # relevance, size, seeders, time
-bt4g_category = 'all'  # all, audio, movie, doc, app, other
+bt4g_order_by = 'relevance'
+"""Result list can be ordered by ``relevance`` (default), ``size``, ``seeders``
+or ``time``.
+
+.. hint::
+
+  When *time_range* is activate, the results always orderd by ``time``.
+"""
+
+bt4g_category = 'all'
+"""BT$G offers categoies: ``all`` (default), ``audio``, ``movie``, ``doc``,
+``app`` and `` other``.
+"""
 
 
 def request(query, params):