From a5dad3b7c83ce59f30494cdb3fa8f129b690fca2 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 16 Apr 2023 14:23:27 +0200 Subject: [doc] slightly reorder the chapters & improve TOCs for better navigation Signed-off-by: Markus Heiser --- docs/admin/engines/configured_engines.rst | 89 ------------------------------- docs/admin/engines/index.rst | 7 ++- docs/conf.py | 2 +- docs/dev/reST.rst | 2 +- docs/donate.rst | 2 + docs/index.rst | 34 ++++++++---- docs/own-instance.rst | 13 +++-- docs/user/about.rst | 4 ++ docs/user/configured_engines.rst | 89 +++++++++++++++++++++++++++++++ docs/user/index.rst | 10 ++-- docs/user/search-syntax.rst | 4 ++ 11 files changed, 146 insertions(+), 110 deletions(-) delete mode 100644 docs/admin/engines/configured_engines.rst create mode 100644 docs/user/about.rst create mode 100644 docs/user/configured_engines.rst create mode 100644 docs/user/search-syntax.rst (limited to 'docs') diff --git a/docs/admin/engines/configured_engines.rst b/docs/admin/engines/configured_engines.rst deleted file mode 100644 index 9507c77df..000000000 --- a/docs/admin/engines/configured_engines.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. _configured engines: - -================== -Configured Engines -================== - -.. sidebar:: Further reading .. - - - :ref:`settings categories_as_tabs` - - :ref:`engines-dev` - - :ref:`settings engine` - - :ref:`general engine configuration` - -.. jinja:: searx - - SearXNG supports {{engines | length}} search engines of which - {{enabled_engine_count}} are enabled by default. - - Engines can be assigned to multiple :ref:`categories `. - The UI displays the tabs that are configured in :ref:`categories_as_tabs - `. In addition to these UI categories (also - called *tabs*), engines can be queried by their name or the categories they - belong to, by using a :ref:`\!bing syntax `. - -.. contents:: Contents - :depth: 2 - :local: - :backlinks: entry - -.. jinja:: searx - - {% for category, engines in categories_as_tabs.items() %} - - tab ``!{{category.replace(' ', '_')}}`` - --------------------------------------- - - {% for group, group_bang, engines in engines | group_engines_in_tab %} - - {% if loop.length > 1 %} - {% if group_bang %}group ``{{group_bang}}``{% else %}{{group}}{% endif %} - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - {% endif %} - - .. flat-table:: - :header-rows: 2 - :stub-columns: 1 - :widths: 10 1 10 1 1 1 1 1 1 1 - - * - :cspan:`5` Engines configured by default (in :ref:`settings.yml `) - - :cspan:`3` :ref:`Supported features ` - - * - Name - - !bang - - Module - - Disabled - - Timeout - - Weight - - Paging - - Locale - - Safe search - - Time range - - {% for mod in engines %} - - * - `{{mod.name}} <{{mod.about and mod.about.website}}>`_ - {%- if mod.about and mod.about.language %} - ({{mod.about.language | upper}}) - {%- endif %} - - ``!{{mod.shortcut}}`` - - {%- if 'searx.engines.' + mod.__name__ in documented_modules %} - :py:mod:`~searx.engines.{{mod.__name__}}` - {%- else %} - :origin:`{{mod.__name__}} ` - {%- endif %} - - {{(mod.disabled and "y") or ""}} - - {{mod.timeout}} - - {{mod.weight or 1 }} - {% if mod.engine_type == 'online' %} - - {{(mod.paging and "y") or ""}} - - {{(mod.language_support and "y") or ""}} - - {{(mod.safesearch and "y") or ""}} - - {{(mod.time_range_support and "y") or ""}} - {% else %} - - :cspan:`3` not applicable ({{mod.engine_type}}) - {% endif %} - - {% endfor %} - {% endfor %} - {% endfor %} diff --git a/docs/admin/engines/index.rst b/docs/admin/engines/index.rst index f488731ea..92c723817 100644 --- a/docs/admin/engines/index.rst +++ b/docs/admin/engines/index.rst @@ -10,10 +10,13 @@ Engines & Settings - :ref:`engine settings` & :ref:`engine file` .. toctree:: - :maxdepth: 1 + :maxdepth: 3 settings - configured_engines + +.. toctree:: + :maxdepth: 1 + private-engines recoll sql-engines diff --git a/docs/conf.py b/docs/conf.py index 1d71b7f8a..88a9db958 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,7 +68,7 @@ jinja_filters = { # Let the Jinja template in configured_engines.rst access documented_modules # to automatically link documentation for modules if it exists. def setup(app): - ENGINES_DOCNAME = 'admin/engines/configured_engines' + ENGINES_DOCNAME = 'user/configured_engines' def before_read_docs(app, env, docnames): assert ENGINES_DOCNAME in docnames diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index e5d49f672..10f6531f2 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -1284,7 +1284,7 @@ install` (with SearXNG modules installed). We use this e.g. to build chapter: :ref:`configured engines`. Below the jinja directive from the :origin:`docs/admin/engines.rst` is shown: -.. literalinclude:: ../admin/engines/configured_engines.rst +.. literalinclude:: ../user/configured_engines.rst :language: reST :start-after: .. _configured engines: diff --git a/docs/donate.rst b/docs/donate.rst index b68ed807b..072243262 100644 --- a/docs/donate.rst +++ b/docs/donate.rst @@ -1,3 +1,5 @@ +.. _donate: + Donate to searxng.org ===================== diff --git a/docs/index.rst b/docs/index.rst index f331e3211..564fa7dba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,21 +11,37 @@ SearXNG can be used over Tor for online anonymity. Get started with SearXNG by using one of the instances listed at searx.space_. If you don't trust anyone, you can set up your own, see :ref:`installation`. -.. sidebar:: Features +.. sidebar:: features - - Self hosted - - No user tracking - - No user profiling - - About 70 supported search engines - - Easy integration with any search engine - - Cookies are not used by default - - Secure, encrypted connections (HTTPS/SSL) + - :ref:`self hosted ` + - :ref:`no user tracking / no profiling ` + - script & cookies are optional + - secure, encrypted connections + - :ref:`about 130 search engines ` + - `about 60 translations `_ + - about 100 `well maintained `__ instances on searx.space_ + - :ref:`easy integration of search engines ` + - professional development: `CI `_, + `quality assurance `_ & + `automated tested UI `_ -.. sidebar:: info +.. sidebar:: be a part + + SearXNG is driven by an open community, come join us! You can :ref:`donate + `, but much more we appreciate contributions. Don't hesitate, no + need to be an *expert*, everyone can contribute: + + - `help to improve translations `_ + - `discuss with the community `_ + - report bugs & suggestions + - ... + +.. sidebar:: the origin SearXNG development has been started in the middle of 2021 as a fork of the searx project. + .. toctree:: :maxdepth: 2 :caption: Contents diff --git a/docs/own-instance.rst b/docs/own-instance.rst index c53f28307..d1124c389 100644 --- a/docs/own-instance.rst +++ b/docs/own-instance.rst @@ -2,10 +2,15 @@ Why use a private instance? =========================== - *"Is it worth to run my own instance?"* +.. sidebar:: Is it worth to run my own instance? -\.\. is a common question among SearXNG users. Before answering this question, -see what options a SearXNG user has. + \.\. is a common question among SearXNG users. Before answering this + question, see what options a SearXNG user has. + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: entry Public instances are open to everyone who has access to its URL. Usually, these are operated by unknown parties (from the users' point of view). Private @@ -16,6 +21,8 @@ single user one which runs on the user's laptop. To gain more insight on how these instances work let's dive into how SearXNG protects its users. +.. _SearXNG protect privacy: + How does SearXNG protect privacy? ================================= diff --git a/docs/user/about.rst b/docs/user/about.rst new file mode 100644 index 000000000..08f1a068e --- /dev/null +++ b/docs/user/about.rst @@ -0,0 +1,4 @@ +.. _about SearXNG: + +.. include:: about.md + :parser: myst_parser.sphinx_ diff --git a/docs/user/configured_engines.rst b/docs/user/configured_engines.rst new file mode 100644 index 000000000..9507c77df --- /dev/null +++ b/docs/user/configured_engines.rst @@ -0,0 +1,89 @@ +.. _configured engines: + +================== +Configured Engines +================== + +.. sidebar:: Further reading .. + + - :ref:`settings categories_as_tabs` + - :ref:`engines-dev` + - :ref:`settings engine` + - :ref:`general engine configuration` + +.. jinja:: searx + + SearXNG supports {{engines | length}} search engines of which + {{enabled_engine_count}} are enabled by default. + + Engines can be assigned to multiple :ref:`categories `. + The UI displays the tabs that are configured in :ref:`categories_as_tabs + `. In addition to these UI categories (also + called *tabs*), engines can be queried by their name or the categories they + belong to, by using a :ref:`\!bing syntax `. + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: entry + +.. jinja:: searx + + {% for category, engines in categories_as_tabs.items() %} + + tab ``!{{category.replace(' ', '_')}}`` + --------------------------------------- + + {% for group, group_bang, engines in engines | group_engines_in_tab %} + + {% if loop.length > 1 %} + {% if group_bang %}group ``{{group_bang}}``{% else %}{{group}}{% endif %} + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + {% endif %} + + .. flat-table:: + :header-rows: 2 + :stub-columns: 1 + :widths: 10 1 10 1 1 1 1 1 1 1 + + * - :cspan:`5` Engines configured by default (in :ref:`settings.yml `) + - :cspan:`3` :ref:`Supported features ` + + * - Name + - !bang + - Module + - Disabled + - Timeout + - Weight + - Paging + - Locale + - Safe search + - Time range + + {% for mod in engines %} + + * - `{{mod.name}} <{{mod.about and mod.about.website}}>`_ + {%- if mod.about and mod.about.language %} + ({{mod.about.language | upper}}) + {%- endif %} + - ``!{{mod.shortcut}}`` + - {%- if 'searx.engines.' + mod.__name__ in documented_modules %} + :py:mod:`~searx.engines.{{mod.__name__}}` + {%- else %} + :origin:`{{mod.__name__}} ` + {%- endif %} + - {{(mod.disabled and "y") or ""}} + - {{mod.timeout}} + - {{mod.weight or 1 }} + {% if mod.engine_type == 'online' %} + - {{(mod.paging and "y") or ""}} + - {{(mod.language_support and "y") or ""}} + - {{(mod.safesearch and "y") or ""}} + - {{(mod.time_range_support and "y") or ""}} + {% else %} + - :cspan:`3` not applicable ({{mod.engine_type}}) + {% endif %} + + {% endfor %} + {% endfor %} + {% endfor %} diff --git a/docs/user/index.rst b/docs/user/index.rst index af2051f01..4603b4716 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -7,9 +7,9 @@ User information :local: :backlinks: entry +.. toctree:: + :maxdepth: 2 -.. _search-syntax: - -.. include:: search-syntax.md - :parser: myst_parser.sphinx_ - + search-syntax + configured_engines + about diff --git a/docs/user/search-syntax.rst b/docs/user/search-syntax.rst new file mode 100644 index 000000000..3acddd6e3 --- /dev/null +++ b/docs/user/search-syntax.rst @@ -0,0 +1,4 @@ +.. _search-syntax: + +.. include:: search-syntax.md + :parser: myst_parser.sphinx_ -- cgit v1.2.3