From 05149db4c1e495eecaf74d267e91f61dee7ee40d Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Sat, 15 Jan 2022 06:09:37 +0100 Subject: [PATCH 1/3] [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(): From 284ac8bfd8a3d1f762c98a0195b98a45cdd089d3 Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Sat, 15 Jan 2022 09:01:38 +0100 Subject: [PATCH 2/3] [help] convert about.html to Markdown To facilitate translation the new user documentation shall be written in Markdown (which is more human-friendly than HTML and reStructuredText). --- requirements.txt | 1 + searx/help/about.html | 102 ------------------------------------------ searx/help/about.md | 80 +++++++++++++++++++++++++++++++++ searx/user_help.py | 5 ++- 4 files changed, 84 insertions(+), 104 deletions(-) delete mode 100644 searx/help/about.html create mode 100644 searx/help/about.md diff --git a/requirements.txt b/requirements.txt index e9fd942d1..95b85578e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -14,3 +14,4 @@ httpx-socks[asyncio]==0.7.2 langdetect==1.0.9 setproctitle==1.2.2 redis==4.1.1 +mistletoe==0.8.1 diff --git a/searx/help/about.html b/searx/help/about.html deleted file mode 100644 index 5a9065f03..000000000 --- a/searx/help/about.html +++ /dev/null @@ -1,102 +0,0 @@ - -

About searxng

- -

- SearXNG is a fork from the well-known searx - metasearch engine, - aggregating the results of other search engines - while not storing information about its users. -

- -

More about SearXNG ...

- - - -
- -

Why use it?

- -
    -
  • - SearXNG may not offer you as personalised results as Google, but it doesn't - generate a profile about you. -
    • -
  • - SearXNG doesn't care about what you search for, never shares anything with a - third party, and it can't be used to compromise you. -
    • -
  • - SearXNG is free software, the code is 100% open and you can help to make - it better. See more on SearXNG sources. -
    • -
- -

- If you do care about privacy, want to be a conscious user, or otherwise - believe in digital freedom, make SearXNG your default search engine or run - it on your own server -

- -

Technical details - How does it work?

- -

- SearXNG is a metasearch engine, - inspired by the seeks project. - - It provides basic privacy by mixing your queries with searches on other - platforms without storing search data. Queries are made using a POST request - on every browser (except Chromium-based browsers*). Therefore they show up - in neither our logs, nor your url history. In the case of Chromium-based - browser users there is an exception: searx uses the search bar to perform GET - requests. - - SearXNG can be added to your browser's search bar; moreover, it can be set as - the default search engine. -

- -

How to set as the default search engine?

- -

- SearXNG supports OpenSearch. - For more information on changing your default search engine, see your browser's documentation: -

- - - -

Where to find anonymous usage statistics of this instance ?

- -

- Stats page contains some useful data about the engines used. -

- -

How can I make it my own?

- -

- SearXNG appreciates your concern regarding logs, so take the code from - the SearXNG project and - run it yourself! -

-

- Add your instance to this list of - public instances to help other people reclaim their privacy and make the - Internet freer! The more decentralized the Internet is, the more freedom we - have! -

- -

Where are the docs & code of this instance?

- -

- See the SearXNG docs - and SearXNG sources -

- - -{% include "__common__/aboutextend.html" ignore missing %} diff --git a/searx/help/about.md b/searx/help/about.md new file mode 100644 index 000000000..00822e89c --- /dev/null +++ b/searx/help/about.md @@ -0,0 +1,80 @@ +# About [searxng][url_for:index] + +SearXNG is a fork from the well-known [searx] [metasearch engine], aggregating +the results of other [search engines][url_for:preferences] while not storing +information about its users. + +More about SearXNG ... + +* [SearXNG sources][brand.git_url] +* [weblate] + +--- + +## Why use it? + +* SearXNG may not offer you as personalised results as Google, + but it doesn't generate a profile about you. + +* SearXNG doesn't care about what you search for, never shares anything + with a third party, and it can't be used to compromise you. + +* SearXNG is free software, the code is 100% open and you can help + to make it better. See more on [SearXNG sources][brand.git_url]. + +If you do care about privacy, want to be a conscious user, or otherwise +believe in digital freedom, make SearXNG your default search engine or run +it on your own server + +## Technical details - How does it work? + +SearXNG is a [metasearch engine], inspired by the [seeks project]. It provides +basic privacy by mixing your queries with searches on other platforms without +storing search data. Queries are made using a POST request on every browser +(except Chromium-based browsers*). Therefore they show up in neither our logs, +nor your url history. In the case of Chromium-based browser users there is an +exception: searx uses the search bar to perform GET requests. SearXNG can be +added to your browser's search bar; moreover, it can be set as the default +search engine. + + +## How to set as the default search engine? + +SearXNG supports [OpenSearch]. For more information on changing your default +search engine, see your browser's documentation: + +* [Firefox](https://support.mozilla.org/en-US/kb/add-or-remove-search-engine-firefox) +* [Microsoft Edge](https://support.microsoft.com/en-us/help/4028574/microsoft-edge-change-the-default-search-engine) +* Chromium-based browsers [only add websites that the user navigates to without a path.](https://www.chromium.org/tab-to-search) + +## Where to find anonymous usage statistics of this instance ? + +[Stats page][url_for:stats] contains some useful data about the engines used. + +## How can I make it my own? + +SearXNG appreciates your concern regarding logs, so take the code from +the [SearXNG project][brand.git_url] and run it yourself! + +Add your instance to this [list of public instances][brand.public_instances] to +help other people reclaim their privacy and make the Internet freer! The more +decentralized the Internet is, the more freedom we have! + +## Where are the docs & code of this instance? + +See the [SearXNG docs][brand.docs_url] and [SearXNG sources][brand.git_url] + +[url_for:index]: {{ url_for('index') }} +[url_for:preferences]: {{ url_for('preferences') }} +[url_for:stats]: {{ url_for('stats') }} +[brand.git_url]: {{ searx_git_url }} +[brand.public_instances]: {{ get_setting('brand.public_instances') }} +[brand.docs_url]: {{ get_setting('brand.docs_url') }} + +[searx]: https://github.com/searx/searx +[metasearch engine]: https://en.wikipedia.org/wiki/Metasearch_engine +[weblate]: https://weblate.bubu1.eu/projects/searxng/ +[seeks project]: https://beniz.github.io/seeks/ +[OpenSearch]: https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md + +{% include "__common__/aboutextend.html" ignore missing %} diff --git a/searx/user_help.py b/searx/user_help.py index 2822d3a0d..1d3cbef37 100644 --- a/searx/user_help.py +++ b/searx/user_help.py @@ -3,6 +3,7 @@ import os.path import pkg_resources import flask +import mistletoe from . import get_setting from .version import GIT_URL @@ -20,7 +21,7 @@ def render(app: flask.Flask): """ for filename in pkg_resources.resource_listdir(__name__, 'help'): rootname, ext = os.path.splitext(filename) - if ext != '.html': + if ext != '.md': continue text = pkg_resources.resource_string(__name__, 'help/' + filename).decode() @@ -35,4 +36,4 @@ def render(app: flask.Flask): interpolated = flask.render_template_string(text, get_setting=get_setting, searx_git_url=GIT_URL) - HELP[rootname] = interpolated + HELP[rootname] = mistletoe.markdown(interpolated) From 105c5a6a9839c65a81b32cdf82278c5cc629ae4a Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Sat, 15 Jan 2022 09:34:08 +0100 Subject: [PATCH 3/3] [help] stop rendering documentation with Jinja2 To facilitate translation of the user documentation we move the templating logic outside of the user documentation. --- searx/help/about.md | 9 -------- searx/templates/oscar/about.html | 1 + searx/templates/simple/about.html | 1 + searx/user_help.py | 35 +++++++++++++++++++------------ 4 files changed, 24 insertions(+), 22 deletions(-) diff --git a/searx/help/about.md b/searx/help/about.md index 00822e89c..521022414 100644 --- a/searx/help/about.md +++ b/searx/help/about.md @@ -64,17 +64,8 @@ decentralized the Internet is, the more freedom we have! See the [SearXNG docs][brand.docs_url] and [SearXNG sources][brand.git_url] -[url_for:index]: {{ url_for('index') }} -[url_for:preferences]: {{ url_for('preferences') }} -[url_for:stats]: {{ url_for('stats') }} -[brand.git_url]: {{ searx_git_url }} -[brand.public_instances]: {{ get_setting('brand.public_instances') }} -[brand.docs_url]: {{ get_setting('brand.docs_url') }} - [searx]: https://github.com/searx/searx [metasearch engine]: https://en.wikipedia.org/wiki/Metasearch_engine [weblate]: https://weblate.bubu1.eu/projects/searxng/ [seeks project]: https://beniz.github.io/seeks/ [OpenSearch]: https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md - -{% include "__common__/aboutextend.html" ignore missing %} diff --git a/searx/templates/oscar/about.html b/searx/templates/oscar/about.html index ed9b525bc..a644761b6 100644 --- a/searx/templates/oscar/about.html +++ b/searx/templates/oscar/about.html @@ -2,4 +2,5 @@ {% block title %}{{ _('about') }} - {% endblock %} {% block content %} {{ help.about | safe }} +{% include "__common__/aboutextend.html" ignore missing %} {% endblock %} diff --git a/searx/templates/simple/about.html b/searx/templates/simple/about.html index a59699367..9f6a10ced 100644 --- a/searx/templates/simple/about.html +++ b/searx/templates/simple/about.html @@ -1,4 +1,5 @@ {% extends 'simple/base.html' %} {% block content %} {{ help.about | safe }} +{% include "__common__/aboutextend.html" ignore missing %} {% endblock %} diff --git a/searx/user_help.py b/searx/user_help.py index 1d3cbef37..bf7336777 100644 --- a/searx/user_help.py +++ b/searx/user_help.py @@ -3,6 +3,7 @@ import os.path import pkg_resources import flask +from flask.helpers import url_for import mistletoe from . import get_setting @@ -19,21 +20,29 @@ def render(app: flask.Flask): We render the user documentation once on startup to improve performance. """ + + link_targets = { + 'brand.git_url': GIT_URL, + 'brand.public_instances': get_setting('brand.public_instances'), + 'brand.docs_url': get_setting('brand.docs_url'), + } + + 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): + link_targets['url_for:index'] = url_for('index') + link_targets['url_for:preferences'] = url_for('preferences') + link_targets['url_for:stats'] = url_for('stats') + + define_link_targets = ''.join(f'[{name}]: {url}\n' for name, url in link_targets.items()) + for filename in pkg_resources.resource_listdir(__name__, 'help'): rootname, ext = os.path.splitext(filename) + if ext != '.md': 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] = mistletoe.markdown(interpolated) + markdown = pkg_resources.resource_string(__name__, 'help/' + filename).decode() + markdown = define_link_targets + markdown + HELP[rootname] = mistletoe.markdown(markdown)