[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``: ``results_on_new_tab``:
Open result links in a new tab by default. Open result links in a new tab by default.
.. _settings redis: .. _settings redis:
``redis:`` ``redis:``
@ -457,6 +456,9 @@ Communication with search engines.
``max_redirects`` : ``max_redirects`` :
30 by default. Maximum redirect before it is an error. 30 by default. Maximum redirect before it is an error.
.. _settings categories_as_tabs:
``categories_as_tabs:`` ``categories_as_tabs:``
----------------------- -----------------------
@ -477,6 +479,15 @@ Categories not listed here can still be searched with the :ref:`search-syntax`.
files: files:
social media: 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: .. _settings engine:
Engine settings 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 to build and send a ``Accept-Language`` header in the request to the origin
search engine. search engine.
.. _engine categories:
``categories`` : optional ``categories`` : optional
Define in which categories this engine will be active. Most of the time, it is Specifies to which categories the engine should be added. Engines can be
defined in the code of the engine, but in a few cases it is useful, like when assigned to multiple categories.
describing multiple search engine using the same code.
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`` : optional
Timeout of the search with the current search engine. **Be careful, it will Timeout of the search with the current search engine. **Be careful, it will

View File

@ -46,7 +46,7 @@ Engine File
======================= =========== ======================================================== ======================= =========== ========================================================
argument type information 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 paging boolean support multiple pages
time_range_support boolean support search time range time_range_support boolean support search time range
engine_type str - ``online`` :ref:`[ref] <demo online engine>` by 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 # settings.yml
categories: List[str] categories: List[str]
"""Tabs, in which the engine is working.""" """Specifies to which :ref:`engine categories` the engine should be added."""
name: str name: str
"""Name that will be used across SearXNG to define this engine. In settings, on """Name that will be used across SearXNG to define this engine. In settings, on