From 4a36a3044d6e39bc60d026d99ed7a010f6505a5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= <kvch@users.noreply.github.com>
Date: Mon, 30 Nov 2020 08:35:15 +0100
Subject: Add recoll engine (#2325)

recoll is a local search engine based on Xapian:
http://www.lesbonscomptes.com/recoll/

By itself recoll does not offer web or API access,
this can be achieved using recoll-webui:
https://framagit.org/medoc92/recollwebui.git

This engine uses a custom 'files' result template

set `base_url` to the location where recoll-webui can be reached
set `dl_prefix` to a location where the file hierarchy as indexed by recoll can be reached
set `search_dir` to the part of the indexed file hierarchy to be searched, use an empty string to search the entire search domain
---
 docs/admin/engines.rst        | 25 ++++++++++++++++------
 docs/admin/engines/recoll.rst | 50 +++++++++++++++++++++++++++++++++++++++++++
 docs/dev/engine_overview.rst  |  3 +++
 3 files changed, 72 insertions(+), 6 deletions(-)
 create mode 100644 docs/admin/engines/recoll.rst

(limited to 'docs')

diff --git a/docs/admin/engines.rst b/docs/admin/engines.rst
index 4d1872dfc..f1ac03699 100644
--- a/docs/admin/engines.rst
+++ b/docs/admin/engines.rst
@@ -1,14 +1,28 @@
-.. _engines generic:
-
 =======
 Engines
 =======
 
+Special Engine Settings
+=======================
+
 .. sidebar:: Further reading ..
 
    - :ref:`settings engine`
-   - :ref:`engine settings`
-   - :ref:`engine file`
+   - :ref:`engine settings` & :ref:`engine file`
+
+.. toctree::
+   :maxdepth: 1
+
+   engines/recoll.rst
+
+
+.. _engines generic:
+
+General Engine Settings
+=======================
+
+Explanation of the :ref:`general engine configuration` shown in the table
+:ref:`configured engines`.
 
 ============= =========== ==================== ============
 :ref:`engine settings`    :ref:`engine file`
@@ -30,8 +44,6 @@ Disabled      **D**
 Show errors   **DE**
 ============= =========== =================================
 
-Configuration defaults (at built time):
-
 .. _configured engines:
 
 .. jinja:: webapp
@@ -73,3 +85,4 @@ Configuration defaults (at built time):
         - {{(mod.display_error_messages and "y") or ""}}
 
      {% endfor %}
+
diff --git a/docs/admin/engines/recoll.rst b/docs/admin/engines/recoll.rst
new file mode 100644
index 000000000..cba2e81f7
--- /dev/null
+++ b/docs/admin/engines/recoll.rst
@@ -0,0 +1,50 @@
+.. _engine recoll:
+
+======
+Recoll
+======
+
+.. sidebar:: info
+
+   - `Recoll <https://www.lesbonscomptes.com/recoll/>`_
+   - `recoll-webui <https://framagit.org/medoc92/recollwebui.git>`_
+
+Recoll_ is a desktop full-text search tool based on Xapian. By itself Recoll_
+does not offer web or API access, this can be achieved using recoll-webui_
+
+
+
+Configuration
+=============
+
+You must configure the following settings:
+
+``base_url``:
+  Location where recoll-webui can be reached.
+
+``mount_prefix``:
+  Location where the file hierarchy is mounted on your *local* filesystem.
+
+``dl_prefix``:
+  Location where the file hierarchy as indexed by recoll can be reached.
+
+``search_dir``:
+  Part of the indexed file hierarchy to be search, if empty the full domain is
+  searched.
+
+
+Example
+=======
+
+Scenario:
+
+#. Recoll indexes a local filesystem mounted in ``/export/documents/reference``,
+#. the Recoll search inteface can be reached at https://recoll.example.org/ and
+#. the contents of this filesystem can be reached though https://download.example.org/reference
+
+.. code:: yaml
+
+   base_url: https://recoll.example.org/
+   mount_prefix: /export/documents
+   dl_prefix: https://download.example.org
+   search_dir: ''
diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst
index 268995a45..5e3483fd7 100644
--- a/docs/dev/engine_overview.rst
+++ b/docs/dev/engine_overview.rst
@@ -18,6 +18,9 @@ engines.  Adapters are stored under the folder :origin:`searx/engines`.
    :depth: 3
    :backlinks: entry
 
+
+.. _general engine configuration:
+
 general engine configuration
 ============================
 
-- 
cgit v1.2.3