From 8f79dd7659a3d837108b402dcd482910d55b57d8 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 24 Jul 2022 10:51:22 +0200 Subject: [PATCH] [doc] additional descriptions about categories & categories_as_tabs Add missing documentation of PR [#634]. Related to checkbox "Document how to categorize engines" in [#690]. Related: - [#634] https://github.com/searxng/searxng/pull/634#issuecomment-1004757502 - [#690] https://github.com/searxng/searxng/issues/690 - https://github.com/searxng/searxng/issues/1604 - https://github.com/searxng/searxng/pull/1545 Signed-off-by: Markus Heiser --- docs/admin/engines/settings.rst | 34 +++++++++++++++++++++++++++------ docs/dev/engine_overview.rst | 2 +- searx/enginelib/__init__.py | 2 +- 3 files changed, 30 insertions(+), 8 deletions(-) diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst index 0d9e14e57..fa61f6212 100644 --- a/docs/admin/engines/settings.rst +++ b/docs/admin/engines/settings.rst @@ -311,7 +311,6 @@ Global Settings ``results_on_new_tab``: Open result links in a new tab by default. - .. _settings redis: ``redis:`` @@ -451,12 +450,15 @@ Communication with search engines. see `httpx verification defaults`_. In addition to ``verify``, SearXNG supports the ``$SSL_CERT_FILE`` (for a file) and - ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables. + ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables. see `httpx ssl configuration`_. ``max_redirects`` : 30 by default. Maximum redirect before it is an error. + +.. _settings categories_as_tabs: + ``categories_as_tabs:`` ----------------------- @@ -477,6 +479,15 @@ Categories not listed here can still be searched with the :ref:`search-syntax`. files: social media: +Engines are added to ``categories:`` (compare :ref:`engine categories`), the +categories listed in ``categories_as_tabs`` are shown as tabs in the UI. If +there are no active engines in a category, the tab is not displayed (e.g. if a +user disables all engines in a category). + +On the preferences page (``/preferences``) -- under *engines* -- there is an +additional tab, called *other*. In this tab are all engines listed that are not +in one of the UI tabs (not included in ``categories_as_tabs``). + .. _settings engine: Engine settings @@ -552,10 +563,21 @@ engine is shown. Most of the options have a default value or even are optional. to build and send a ``Accept-Language`` header in the request to the origin search engine. +.. _engine categories: + ``categories`` : optional - Define in which categories this engine will be active. Most of the time, it is - defined in the code of the engine, but in a few cases it is useful, like when - describing multiple search engine using the same code. + Specifies to which categories the engine should be added. Engines can be + assigned to multiple categories. + + Categories can be shown as tabs (:ref:`settings categories_as_tabs`) in the + UI. A search in a tab (in the UI) will query all engines that are active in + this tab. In the preferences page (``/preferences``) -- under *engines* -- + users can select what engine should be active when querying in this tab. + + Alternatively, :ref:`\!bang ` can be used to search all engines + in a category, regardless of whether they are active or not, or whether they + are in a tab of the UI or not. For example, ``!dictionaries`` can be used to + query all search engines in that category (group). ``timeout`` : optional Timeout of the search with the current search engine. **Be careful, it will @@ -658,7 +680,7 @@ and can relied on the default configuration :origin:`searx/settings.yml` using: ``engines:`` With ``use_default_settings: true``, each settings can be override in a similar way, the ``engines`` section is merged according to the engine - ``name``. In this example, SearXNG will load all the default engines, will + ``name``. In this example, SearXNG will load all the default engines, will enable the ``bing`` engine and define a :ref:`token ` for the arch linux engine: diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 930fd0813..5fd31c01d 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -46,7 +46,7 @@ Engine File ======================= =========== ======================================================== argument type information ======================= =========== ======================================================== - categories list pages, in which the engine is working + categories list categories, in which the engine is working paging boolean support multiple pages time_range_support boolean support search time range engine_type str - ``online`` :ref:`[ref] ` by diff --git a/searx/enginelib/__init__.py b/searx/enginelib/__init__.py index 461791b18..00962e215 100644 --- a/searx/enginelib/__init__.py +++ b/searx/enginelib/__init__.py @@ -81,7 +81,7 @@ class Engine: # pylint: disable=too-few-public-methods # settings.yml categories: List[str] - """Tabs, in which the engine is working.""" + """Specifies to which :ref:`engine categories` the engine should be added.""" name: str """Name that will be used across SearXNG to define this engine. In settings, on