From 1d6597b40773b688ca317e1ab1ffe133b370afb1 Mon Sep 17 00:00:00 2001 From: Adam Tauber Date: Tue, 17 Nov 2015 23:13:30 +0100 Subject: [enh] initial structure --- docs/dev/search_api.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/dev/search_api.rst (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst new file mode 100644 index 000000000..cd86fd71c --- /dev/null +++ b/docs/dev/search_api.rst @@ -0,0 +1,24 @@ +Search API +========== + +Search API endpoints: ``/``, ``/search`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Endpoints have equivalent functionality. + +Parameters +^^^^^^^^^^ + ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| Name | Description | | ++==================+====================================================================================================+=============================+ +| ``q`` | The search query, see :doc:`/user/search_syntax` | required | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| ``categories`` | Comma separated list, specifies the active search categories | optional | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| ``engines`` | Comma separated list, specifies the active search engines | optional | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| ``pageno`` | Search page number | optional (default: ``1``) | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ + +Both ``GET`` and ``POST`` methods are supported. -- cgit v1.2.3 From 2ad8715b3282557d39da21721487ff85683b1219 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Sat, 9 Jul 2016 22:31:21 +0200 Subject: better API docs && more features in list --- docs/dev/search_api.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index cd86fd71c..59d3c825f 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -1,13 +1,20 @@ Search API ========== -Search API endpoints: ``/``, ``/search`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The search supports both ``GET`` and ``POST``. However, using ``GET`` the parameters of the request remain hidden. So it is advised to use ``GET`` for querying. -Endpoints have equivalent functionality. +Furthermore, two enpoints ``/`` and ``/search`` are available for querying. + +.. code:: sh + + GET / + +.. code:: sh + + GET /search Parameters -^^^^^^^^^^ +`````````` +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ | Name | Description | | @@ -18,7 +25,7 @@ Parameters +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ | ``engines`` | Comma separated list, specifies the active search engines | optional | +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| ``lang`` | Code of the language | optional (default: ``all``) | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ | ``pageno`` | Search page number | optional (default: ``1``) | +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ - -Both ``GET`` and ``POST`` methods are supported. -- cgit v1.2.3 From 6d99db7af33f82c00dbb9d11e17a9c6a907591cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Tue, 6 Sep 2016 18:13:20 +0200 Subject: add new search parameter time_range --- docs/dev/search_api.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 59d3c825f..c1bc6a139 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -1,7 +1,7 @@ Search API ========== -The search supports both ``GET`` and ``POST``. However, using ``GET`` the parameters of the request remain hidden. So it is advised to use ``GET`` for querying. +The search supports both ``GET`` and ``POST``. Furthermore, two enpoints ``/`` and ``/search`` are available for querying. @@ -29,3 +29,5 @@ Parameters +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ | ``pageno`` | Search page number | optional (default: ``1``) | +------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ +| ``time_range`` | Time range of search | optional | ++------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -- cgit v1.2.3 From daf736f1dda06507b63520d37e1160de44ba6636 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Sat, 10 Sep 2016 15:12:11 +0200 Subject: add possible values of time_range param --- docs/dev/search_api.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index c1bc6a139..03bb6f3fc 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -16,18 +16,18 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying. Parameters `````````` -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| Name | Description | | -+==================+====================================================================================================+=============================+ -| ``q`` | The search query, see :doc:`/user/search_syntax` | required | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| ``categories`` | Comma separated list, specifies the active search categories | optional | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| ``engines`` | Comma separated list, specifies the active search engines | optional | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| ``lang`` | Code of the language | optional (default: ``all``) | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| ``pageno`` | Search page number | optional (default: ``1``) | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ -| ``time_range`` | Time range of search | optional | -+------------------+----------------------------------------------------------------------------------------------------+-----------------------------+ ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| Name | Description | | ++==================+====================================================================================================+==================================================+ +| ``q`` | The search query, see :doc:`/user/search_syntax` | required | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``categories`` | Comma separated list, specifies the active search categories | optional | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``engines`` | Comma separated list, specifies the active search engines | optional | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``lang`` | Code of the language | optional (default: ``all``) | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``pageno`` | Search page number | optional (default: ``1``) | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``time_range`` | Time range of search | optional (possible: ``day``, ``month``, ``year``)| ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -- cgit v1.2.3 From 74d8ed284dfb5363df4280350a8e29125f67a10a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sun, 9 Jul 2017 22:02:29 +0200 Subject: add format param to search api --- docs/dev/search_api.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 03bb6f3fc..331bc4eb9 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -31,3 +31,5 @@ Parameters +------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ | ``time_range`` | Time range of search | optional (possible: ``day``, ``month``, ``year``)| +------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +| ``format`` | Output format of results | optional (possible: ``json``, ``csv``, ``rss``) | ++------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -- cgit v1.2.3 From 07ef4a3e4afc390ac08fe2ac4b6b2e1195604cd1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Mon, 23 Oct 2017 16:29:43 +0200 Subject: update search api with params and description on syntax --- docs/dev/search_api.rst | 213 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 191 insertions(+), 22 deletions(-) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 331bc4eb9..ea3b0501a 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -5,31 +5,200 @@ The search supports both ``GET`` and ``POST``. Furthermore, two enpoints ``/`` and ``/search`` are available for querying. + +``GET /`` + +``GET /search`` + +Parameters +~~~~~~~~~~ + .. code:: sh - GET / + q + +The search query. This string is passed to external search services. +Thus, searx supports syntax of each search service. For example, ``site:github.com searx`` is a valid +query for Google. However, if simply the query above is passed to any search engine which does not filter its +results based on this syntax, you might not get the results you wanted. + + +See more at :doc:`/user/search_syntax` + +Required. .. code:: sh - GET /search + categories -Parameters -`````````` - -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| Name | Description | | -+==================+====================================================================================================+==================================================+ -| ``q`` | The search query, see :doc:`/user/search_syntax` | required | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``categories`` | Comma separated list, specifies the active search categories | optional | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``engines`` | Comma separated list, specifies the active search engines | optional | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``lang`` | Code of the language | optional (default: ``all``) | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``pageno`` | Search page number | optional (default: ``1``) | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``time_range`` | Time range of search | optional (possible: ``day``, ``month``, ``year``)| -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ -| ``format`` | Output format of results | optional (possible: ``json``, ``csv``, ``rss``) | -+------------------+----------------------------------------------------------------------------------------------------+--------------------------------------------------+ +Comma separated list, specifies the active search categories + +Optional. + +.. code:: sh + + engines + +Comma separated list, specifies the active search engines. + +Optional. + +.. code:: sh + + lang + +Code of the language. + +Optional. + +Default: ``all`` + +.. code:: sh + + pageno + +Search page number. + +Optional. + +Default: ``1`` + +.. code:: sh + + time_range + +Time range of search for engines which support it. See if an engine supports time range search in the preferences page of an instance. + +Optional. + +Possible: ``day``, ``month``, ``year`` + +.. code:: sh + + format + +Output format of results. + +Optional. + +Possible: ``json``, ``csv``, ``rss`` + +.. code:: sh + + results_on_new_tab + +Open search results on new tab. + +Optional. + +Default: ``0`` + +Possible: ``0``, ``1`` + +.. code:: sh + + image_proxy + +Proxy image results through searx. + +Optional. + +Default: ``False`` + +Possible: ``True``, ``False`` + +.. code:: sh + + autocomplete + +Service which completes words as you type. + +Optional. + +Default: empty + +Possible: ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` + +.. code:: sh + + safesearch + +Filter search results of engines which support safe search. See if an engine supports safe search in the preferences page of an instance. + +Optional. + +Default: ``None`` + +Possible: ``0``, ``1``, ``None`` + +.. code:: sh + + theme + +Theme of instance. + +Optional. + +Default: ``oscar`` + +Possible: ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` + +Please note, available themes depend on an instance. It is possible that an instance administrator deleted, created or renamed themes on his/her instance. See the available options in the preferences page of the instance. + +.. code:: sh + + oscar-style + +Style of Oscar theme. It is only parsed if the theme of an instance is ``oscar``. + +Optional. + +Default: ``logicodev`` + +Possible: ``pointhi``, ``logicodev`` + +Please note, available styles depend on an instance. It is possible that an instance administrator deleted, created or renamed styles on his/her instance. See the available options in the preferences page of the instance. + +.. code:: sh + + enabled_plugins + +List of enabled plugins. + +Optional. + +Default: ``HTTPS_rewrite``, ``Self_Informations``, ``Search_on_category_select``, ``Tracker_URL_remover`` + +Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select`` + +.. code:: sh + + disabled_plugins + +List of disabled plugins. + +Optional. + +Default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys`` + +Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select`` + +.. code:: sh + + enabled_engines + +List of enabled engines. + +Optional. + +Possible: all engines + +.. code:: sh + + disabled_engines + +List of disabled engines. + +Optional. + +Possible: all engines -- cgit v1.2.3 From e9fff4fde6d7a8bec3fae087d2afe1fce2145f22 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 12 Dec 2019 19:20:56 +0100 Subject: doc: proofread of the all reST sources (no content change) Normalize reST sources with best practice and KISS in mind. to name a few points: - simplify reST tables - make use of ``literal`` markup for monospace rendering - fix code-blocks for better rendering in HTML - normalize section header markup - limit all lines to a maximum of 79 characters - add option -H to the sudo command used in code blocks - drop useless indentation of lists - ... [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Signed-off-by: Markus Heiser --- docs/dev/search_api.rst | 226 ++++++++++++++---------------------------------- 1 file changed, 67 insertions(+), 159 deletions(-) (limited to 'docs/dev/search_api.rst') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index ea3b0501a..158cab7c5 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -1,3 +1,4 @@ +========== Search API ========== @@ -11,194 +12,101 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying. ``GET /search`` Parameters -~~~~~~~~~~ - -.. code:: sh - - q - -The search query. This string is passed to external search services. -Thus, searx supports syntax of each search service. For example, ``site:github.com searx`` is a valid -query for Google. However, if simply the query above is passed to any search engine which does not filter its -results based on this syntax, you might not get the results you wanted. - - -See more at :doc:`/user/search_syntax` - -Required. - -.. code:: sh - - categories - -Comma separated list, specifies the active search categories - -Optional. - -.. code:: sh - - engines - -Comma separated list, specifies the active search engines. - -Optional. - -.. code:: sh - - lang - -Code of the language. - -Optional. - -Default: ``all`` - -.. code:: sh - - pageno - -Search page number. - -Optional. - -Default: ``1`` - -.. code:: sh - - time_range - -Time range of search for engines which support it. See if an engine supports time range search in the preferences page of an instance. - -Optional. - -Possible: ``day``, ``month``, ``year`` - -.. code:: sh - - format - -Output format of results. - -Optional. - -Possible: ``json``, ``csv``, ``rss`` - -.. code:: sh - - results_on_new_tab - -Open search results on new tab. - -Optional. - -Default: ``0`` - -Possible: ``0``, ``1`` - -.. code:: sh - - image_proxy - -Proxy image results through searx. - -Optional. - -Default: ``False`` - -Possible: ``True``, ``False`` - -.. code:: sh - - autocomplete - -Service which completes words as you type. - -Optional. - -Default: empty - -Possible: ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` - -.. code:: sh - - safesearch - -Filter search results of engines which support safe search. See if an engine supports safe search in the preferences page of an instance. - -Optional. - -Default: ``None`` - -Possible: ``0``, ``1``, ``None`` - -.. code:: sh - - theme - -Theme of instance. - -Optional. +========== -Default: ``oscar`` +``q`` : required + The search query. This string is passed to external search services. Thus, + searx supports syntax of each search service. For example, ``site:github.com + searx`` is a valid query for Google. However, if simply the query above is + passed to any search engine which does not filter its results based on this + syntax, you might not get the results you wanted. -Possible: ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` + See more at :ref:`search-syntax` -Please note, available themes depend on an instance. It is possible that an instance administrator deleted, created or renamed themes on his/her instance. See the available options in the preferences page of the instance. +``categories`` : optional + Comma separated list, specifies the active search categories -.. code:: sh +``engines``: optional + Comma separated list, specifies the active search engines. - oscar-style +``lang``: default ``all`` + Code of the language. -Style of Oscar theme. It is only parsed if the theme of an instance is ``oscar``. +``pageno``: default ``1`` + Search page number. -Optional. +``time_range``: optional + [ ``day``, ``month``, ``year`` ] -Default: ``logicodev`` + Time range of search for engines which support it. See if an engine supports + time range search in the preferences page of an instance. -Possible: ``pointhi``, ``logicodev`` +``format``: optional + [ ``json``, ``csv``, ``rss`` ] -Please note, available styles depend on an instance. It is possible that an instance administrator deleted, created or renamed styles on his/her instance. See the available options in the preferences page of the instance. + Output format of results. -.. code:: sh +``results_on_new_tab``: default ``0`` + [ ``0``, ``1`` ] - enabled_plugins + Open search results on new tab. -List of enabled plugins. +``image_proxy``: default ``False`` + [ ``True``, ``False`` ] -Optional. + Proxy image results through searx. -Default: ``HTTPS_rewrite``, ``Self_Informations``, ``Search_on_category_select``, ``Tracker_URL_remover`` +``autocomplete``: default *empty* + [ ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` ] -Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select`` + Service which completes words as you type. -.. code:: sh +``safesearch``: default ``None`` + [ ``0``, ``1``, ``None`` ] - disabled_plugins + Filter search results of engines which support safe search. See if an engine + supports safe search in the preferences page of an instance. -List of disabled plugins. +``theme``: default ``oscar`` + [ ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` ] -Optional. + Theme of instance. -Default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys`` + Please note, available themes depend on an instance. It is possible that an + instance administrator deleted, created or renamed themes on his/her instance. + See the available options in the preferences page of the instance. -Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select`` +``oscar-style``: default ``logicodev`` + [ ``pointhi``, ``logicodev`` ] -.. code:: sh + Style of Oscar theme. It is only parsed if the theme of an instance is + ``oscar``. - enabled_engines + Please note, available styles depend on an instance. It is possible that an + instance administrator deleted, created or renamed styles on his/her + instance. See the available options in the preferences page of the instance. -List of enabled engines. +``enabled_plugins``: optional + List of enabled plugins. -Optional. + :default: ``HTTPS_rewrite``, ``Self_Informations``, + ``Search_on_category_select``, ``Tracker_URL_remover`` -Possible: all engines + :values: [ ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, + ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, + ``Search_on_category_select`` ] -.. code:: sh +``disabled_plugins``: optional + List of disabled plugins. - disabled_engines + :default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys`` + :values: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, + ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, + ``Search_on_category_select`` -List of disabled engines. +``enabled_engines``: optional : *all* :origin:`engines ` + List of enabled engines. -Optional. +``disabled_engines``: optional : *all* :origin:`engines ` + List of disabled engines. -Possible: all engines -- cgit v1.2.3