[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 <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2022-07-24 10:51:22 +02:00
parent 2ffd446e5c
commit 8f79dd7659
3 changed files with 30 additions and 8 deletions

View file

@ -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 <search-syntax>` 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 <private engines>` for
the arch linux engine:

View file

@ -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] <demo online engine>` by

View file

@ -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