From 05149db4c1e495eecaf74d267e91f61dee7ee40d Mon Sep 17 00:00:00 2001
From: Martin Fischer <martin@push-f.com>
Date: Sat, 15 Jan 2022 06:09:37 +0100
Subject: [PATCH] [help] render user documentation once on startup

Currently we have two kinds of user documentation:

* the about page[1] which is written in HTML and part of the web
  application and can therefore link instance-specific pages
  (like e.g. the preferences) via Jinja variables

* the Sphinx documentation[2] which is written in reStructuredText
  and cannot link instance-specific pages since it doesn't know
  which instance the user is using

The plan is to integrate the user documentation currently in Sphinx
into the application, so that it can also link instance specific pages.
We also want to enable the user documentation to be translated.

This commit implements the first step in this endeavor (see #722).

[1]: searx/templates/__common__/about.html
[2]: docs/user/ (currently served at https://docs.searxng.org/user/)
---
 .../{templates/__common__ => help}/about.html |  0
 searx/templates/oscar/about.html              |  2 +-
 searx/templates/simple/about.html             |  2 +-
 searx/user_help.py                            | 38 +++++++++++++++++++
 searx/webapp.py                               |  4 +-
 5 files changed, 43 insertions(+), 3 deletions(-)
 rename searx/{templates/__common__ => help}/about.html (100%)
 create mode 100644 searx/user_help.py

diff --git a/searx/templates/__common__/about.html b/searx/help/about.html
similarity index 100%
rename from searx/templates/__common__/about.html
rename to searx/help/about.html
diff --git a/searx/templates/oscar/about.html b/searx/templates/oscar/about.html
index bc7fed8e1..ed9b525bc 100644
--- a/searx/templates/oscar/about.html
+++ b/searx/templates/oscar/about.html
@@ -1,5 +1,5 @@
 {% extends "oscar/base.html" %}
 {% block title %}{{ _('about') }} - {% endblock %}
 {% block content %}
-{% include '__common__/about.html' %}
+{{ help.about | safe }}
 {% endblock %}
diff --git a/searx/templates/simple/about.html b/searx/templates/simple/about.html
index 1913879da..a59699367 100644
--- a/searx/templates/simple/about.html
+++ b/searx/templates/simple/about.html
@@ -1,4 +1,4 @@
 {% extends 'simple/base.html' %}
 {% block content %}
-{% include '__common__/about.html' %}
+{{ help.about | safe }}
 {% endblock %}
diff --git a/searx/user_help.py b/searx/user_help.py
new file mode 100644
index 000000000..2822d3a0d
--- /dev/null
+++ b/searx/user_help.py
@@ -0,0 +1,38 @@
+from typing import Dict
+import os.path
+import pkg_resources
+
+import flask
+
+from . import get_setting
+from .version import GIT_URL
+
+HELP: Dict[str, str] = {}
+""" Maps a filename under help/ without the file extension to the rendered HTML. """
+
+
+def render(app: flask.Flask):
+    """
+    Renders the user documentation. Must be called after all Flask routes have been
+    registered, because the documentation might try to link to them with Flask's `url_for`.
+
+    We render the user documentation once on startup to improve performance.
+    """
+    for filename in pkg_resources.resource_listdir(__name__, 'help'):
+        rootname, ext = os.path.splitext(filename)
+        if ext != '.html':
+            continue
+
+        text = pkg_resources.resource_string(__name__, 'help/' + filename).decode()
+
+        base_url = get_setting('server.base_url') or None
+        # we specify base_url so that url_for works for base_urls that have a non-root path
+
+        with app.test_request_context(base_url=base_url):
+            # the request context is needed for Flask's url_for
+            # (otherwise we'd need to set app.config['SERVER_NAME'],
+            # which we don't want)
+
+            interpolated = flask.render_template_string(text, get_setting=get_setting, searx_git_url=GIT_URL)
+
+            HELP[rootname] = interpolated
diff --git a/searx/webapp.py b/searx/webapp.py
index f509fea24..099a42996 100755
--- a/searx/webapp.py
+++ b/searx/webapp.py
@@ -55,6 +55,7 @@ from searx import (
     get_setting,
     settings,
     searx_debug,
+    user_help,
 )
 from searx.data import ENGINE_DESCRIPTIONS
 from searx.results import Timing, UnresponsiveEngine
@@ -867,7 +868,7 @@ def __get_translated_errors(unresponsive_engines: Iterable[UnresponsiveEngine]):
 @app.route('/about', methods=['GET'])
 def about():
     """Render about page"""
-    return render('about.html')
+    return render('about.html', help=user_help.HELP)
 
 
 @app.route('/autocompleter', methods=['GET', 'POST'])
@@ -1359,6 +1360,7 @@ werkzeug_reloader = flask_run_development or (searx_debug and __name__ == "__mai
 if not werkzeug_reloader or (werkzeug_reloader and os.environ.get("WERKZEUG_RUN_MAIN") == "true"):
     plugin_initialize(app)
     search_initialize(enable_checker=True, check_network=True, enable_metrics=settings['general']['enable_metrics'])
+    user_help.render(app)
 
 
 def run():