From 021e1da4c9a8eca7293ad62608cc55da5dfde73f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= <sitbackandwait@gmail.com>
Date: Wed, 23 Oct 2019 13:06:19 +0200
Subject: [PATCH] add post about introducing offline engines

---
 docs/blog/blog.rst           |  1 +
 docs/blog/intro-offline.rst  | 65 ++++++++++++++++++++++++++++++++++++
 docs/conf.py                 |  2 +-
 docs/dev/engine_overview.rst |  2 ++
 4 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 docs/blog/intro-offline.rst

diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst
index 77553d5c..2ccaaa5d 100644
--- a/docs/blog/blog.rst
+++ b/docs/blog/blog.rst
@@ -6,3 +6,4 @@ Blog
 
    python3
    admin
+   intro-offline
diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst
new file mode 100644
index 00000000..91452171
--- /dev/null
+++ b/docs/blog/intro-offline.rst
@@ -0,0 +1,65 @@
+Preparation for offline engines
+===============================
+
+Offline engines
+---------------
+
+To extend the functionality of searx, offline engines are going to be introduced. An offline engine is an engine which does not need Internet connection to perform a search and does not use HTTP to communicate.
+
+Offline engines can be configured as online engines, by adding those to the `engines` list of `settings.yml`. Thus, searx finds the engine file and imports it.
+
+Example skeleton for the new engines:
+
+.. code:: python
+
+    from subprocess import PIPE, Popen
+
+    categories = ['general']
+    offline = True
+
+    def init(settings):
+        pass
+
+    def search(query, params):
+        process = Popen(['ls', query], stdout=PIPE)
+        return_code = process.wait()
+        if return_code != 0:
+            raise RuntimeError('non-zero return code', return_code)
+
+        results = []
+        line = process.stdout.readline()
+        while line:
+            result = parse_line(line)
+            results.append(results)
+
+            line = process.stdout.readline()
+
+        return results
+
+
+Development progress
+--------------------
+
+First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: https://github.com/asciimoo/searx/wiki/Offline-engines
+
+In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests.
+
+As offline searches can return arbitrary results depending on the engine, the current result templates were insufficient to present such results. Thus, a new template is introduced which is caplable of presenting arbitrary key value pairs as a table. You can check out the pull request for more details: https://github.com/asciimoo/searx/pull/1700
+
+Next steps
+----------
+
+Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines.
+
+Acknowledgement
+---------------
+
+This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
+
+.. _Search and Discovery Fund: https://nlnet.nl/discovery
+.. _NLnet Foundation: https://nlnet.nl/
+
+
+| Happy hacking.
+| kvch // 2019.10.21 17:03
+
diff --git a/docs/conf.py b/docs/conf.py
index 52aad663..e71ea13a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,7 +49,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'searx'
-copyright = u'2015-2017, Adam Tauber'
+copyright = u'2015-2019, Adam Tauber, Noémi Ványi'
 author = u'Adam Tauber'
 
 # The version info for the project you're documenting, acts as replacement for
diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst
index d57ca5b3..a6867b5d 100644
--- a/docs/dev/engine_overview.rst
+++ b/docs/dev/engine_overview.rst
@@ -41,6 +41,8 @@ engine file
 +----------------------+-----------+-----------------------------------------+
 | time\_range\_support | boolean   | support search time range               |
 +----------------------+-----------+-----------------------------------------+
+| offline              | boolean   | engine runs offline                     |
++----------------------+-----------+-----------------------------------------+
 
 settings.yml
 ~~~~~~~~~~~~