From bb71ebc3945b8e345bebe45a7d393afba6366ab9 Mon Sep 17 00:00:00 2001 From: Martin Fischer Date: Mon, 31 Jan 2022 14:49:40 +0100 Subject: [docs] move own-instance.rst out of docs/user --- docs/index.rst | 1 + docs/own-instance.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++ docs/user/index.rst | 1 - docs/user/own-instance.rst | 79 ---------------------------------------------- 4 files changed, 80 insertions(+), 80 deletions(-) create mode 100644 docs/own-instance.rst delete mode 100644 docs/user/own-instance.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index f9800f95b..b836f4b4c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,7 @@ If you don't trust anyone, you can set up your own, see :ref:`installation`. :caption: Contents user/index + own-instance admin/index dev/index utils/index diff --git a/docs/own-instance.rst b/docs/own-instance.rst new file mode 100644 index 000000000..c53f28307 --- /dev/null +++ b/docs/own-instance.rst @@ -0,0 +1,79 @@ +=========================== +Why use a private instance? +=========================== + + *"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. + +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 +instances can be used by a select group of people. It is for example a SearXNG of +group of friends or a company which can be accessed through VPN. Also it can be +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. + +How does SearXNG protect privacy? +================================= + +SearXNG protects the privacy of its users in multiple ways regardless of the type +of the instance (private, public). Removal of private data from search requests +comes in three forms: + + 1. removal of private data from requests going to search services + 2. not forwarding anything from a third party services through search services + (e.g. advertisement) + 3. removal of private data from requests going to the result pages + +Removing private data means not sending cookies to external search engines and +generating a random browser profile for every request. Thus, it does not matter +if a public or private instance handles the request, because it is anonymized in +both cases. IP addresses will be the IP of the instance. But SearXNG can be +configured to use proxy or Tor. `Result proxy +`__ is supported, too. + +SearXNG does not serve ads or tracking content unlike most search services. So +private data is not forwarded to third parties who might monetize it. Besides +protecting users from search services, both referring page and search query are +hidden from visited result pages. + + +What are the consequences of using public instances? +---------------------------------------------------- + +If someone uses a public instance, they have to trust the administrator of that +instance. This means that the user of the public instance does not know whether +their requests are logged, aggregated and sent or sold to a third party. + +Also, public instances without proper protection are more vulnerable to abusing +the search service, In this case the external service in exchange returns +CAPTCHAs or bans the IP of the instance. Thus, search requests return less +results. + +I see. What about private instances? +------------------------------------ + +If users run their :ref:`own instances `, everything is in their +control: the source code, logging settings and private data. Unknown instance +administrators do not have to be trusted. + +Furthermore, as the default settings of their instance is editable, there is no +need to use cookies to tailor SearXNG to their needs. So preferences will not be +reset to defaults when clearing browser cookies. As settings are stored on +their computer, it will not be accessible to others as long as their computer is +not compromised. + +Conclusion +========== + +Always use an instance which is operated by people you trust. The privacy +features of SearXNG are available to users no matter what kind of instance they +use. + +If someone is on the go or just wants to try SearXNG for the first time public +instances are the best choices. Additionally, public instance are making a +world a better place, because those who cannot or do not want to run an +instance, have access to a privacy respecting search service. diff --git a/docs/user/index.rst b/docs/user/index.rst index 96d11bf8a..0cdb7310c 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -7,4 +7,3 @@ User documentation :caption: Contents search_syntax - own-instance diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst deleted file mode 100644 index c53f28307..000000000 --- a/docs/user/own-instance.rst +++ /dev/null @@ -1,79 +0,0 @@ -=========================== -Why use a private instance? -=========================== - - *"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. - -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 -instances can be used by a select group of people. It is for example a SearXNG of -group of friends or a company which can be accessed through VPN. Also it can be -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. - -How does SearXNG protect privacy? -================================= - -SearXNG protects the privacy of its users in multiple ways regardless of the type -of the instance (private, public). Removal of private data from search requests -comes in three forms: - - 1. removal of private data from requests going to search services - 2. not forwarding anything from a third party services through search services - (e.g. advertisement) - 3. removal of private data from requests going to the result pages - -Removing private data means not sending cookies to external search engines and -generating a random browser profile for every request. Thus, it does not matter -if a public or private instance handles the request, because it is anonymized in -both cases. IP addresses will be the IP of the instance. But SearXNG can be -configured to use proxy or Tor. `Result proxy -`__ is supported, too. - -SearXNG does not serve ads or tracking content unlike most search services. So -private data is not forwarded to third parties who might monetize it. Besides -protecting users from search services, both referring page and search query are -hidden from visited result pages. - - -What are the consequences of using public instances? ----------------------------------------------------- - -If someone uses a public instance, they have to trust the administrator of that -instance. This means that the user of the public instance does not know whether -their requests are logged, aggregated and sent or sold to a third party. - -Also, public instances without proper protection are more vulnerable to abusing -the search service, In this case the external service in exchange returns -CAPTCHAs or bans the IP of the instance. Thus, search requests return less -results. - -I see. What about private instances? ------------------------------------- - -If users run their :ref:`own instances `, everything is in their -control: the source code, logging settings and private data. Unknown instance -administrators do not have to be trusted. - -Furthermore, as the default settings of their instance is editable, there is no -need to use cookies to tailor SearXNG to their needs. So preferences will not be -reset to defaults when clearing browser cookies. As settings are stored on -their computer, it will not be accessible to others as long as their computer is -not compromised. - -Conclusion -========== - -Always use an instance which is operated by people you trust. The privacy -features of SearXNG are available to users no matter what kind of instance they -use. - -If someone is on the go or just wants to try SearXNG for the first time public -instances are the best choices. Additionally, public instance are making a -world a better place, because those who cannot or do not want to run an -instance, have access to a privacy respecting search service. -- cgit v1.2.3 From b1912607ae9783d6ccf648bd7706a64eca5bedb9 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 12 Mar 2022 10:18:08 +0100 Subject: [mod] replace /help by /info pages and include pages in project docs This patch implements a bolierplate to share content from info-pages of the SearXNG instance (URL /info) with the project documentation (path /docs/user). The info pages are using Markdown (CommonMark), to include them in the project documentation (reST) the myst-parser [1] is used in the Sphinx-doc build chain. If base_url is known (defined in settings.yml) links to the instance are also inserted into the project documentation:: searxng_extra/docs_prebuild [1] https://www.sphinx-doc.org/en/master/usage/markdown.html Signed-off-by: Markus Heiser --- docs/conf.py | 6 ++++-- docs/src/searx.infopage.rst | 8 ++++++++ docs/user/.gitignore | 1 + docs/user/index.rst | 14 ++++++++++---- docs/user/search_syntax.rst | 39 --------------------------------------- 5 files changed, 23 insertions(+), 45 deletions(-) create mode 100644 docs/src/searx.infopage.rst create mode 100644 docs/user/.gitignore delete mode 100644 docs/user/search_syntax.rst (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 2f58bdb12..89d6bb8f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,7 +35,7 @@ master_doc = "index" source_suffix = '.rst' numfig = True -exclude_patterns = ['build-templates/*.rst'] +exclude_patterns = ['build-templates/*.rst', 'user/*.md'] import searx.engines import searx.plugins @@ -94,7 +94,6 @@ extlinks['pull-searx'] = ('https://github.com/searx/searx/pull/%s', 'PR ') # links to custom brand extlinks['origin'] = (GIT_URL + '/blob/' + GIT_BRANCH + '/%s', 'git://') extlinks['patch'] = (GIT_URL + '/commit/%s', '#') -extlinks['search'] = (SEARXNG_URL + '/%s', '#') extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ') extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ') extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '') @@ -123,8 +122,11 @@ extensions = [ 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling. "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs + 'myst_parser', # https://www.sphinx-doc.org/en/master/usage/markdown.html ] +suppress_warnings = ['myst.domains'] + intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "flask": ("https://flask.palletsprojects.com/", None), diff --git a/docs/src/searx.infopage.rst b/docs/src/searx.infopage.rst new file mode 100644 index 000000000..243e5b0bd --- /dev/null +++ b/docs/src/searx.infopage.rst @@ -0,0 +1,8 @@ +.. _searx.infopage: + +================ +Online ``/info`` +================ + +.. automodule:: searx.infopage + :members: diff --git a/docs/user/.gitignore b/docs/user/.gitignore new file mode 100644 index 000000000..2e1fa2d52 --- /dev/null +++ b/docs/user/.gitignore @@ -0,0 +1 @@ +*.md \ No newline at end of file diff --git a/docs/user/index.rst b/docs/user/index.rst index 0cdb7310c..dc9fb0da2 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -2,8 +2,14 @@ User documentation ================== -.. toctree:: - :maxdepth: 2 - :caption: Contents +.. contents:: Contents + :depth: 3 + :local: + :backlinks: entry + + +.. _search-syntax: + +.. include:: search-syntax.md + :parser: myst_parser.sphinx_ - search_syntax diff --git a/docs/user/search_syntax.rst b/docs/user/search_syntax.rst deleted file mode 100644 index 346b3162d..000000000 --- a/docs/user/search_syntax.rst +++ /dev/null @@ -1,39 +0,0 @@ - -.. _search-syntax: - -============= -Search syntax -============= - -SearXNG allows you to modify the default categories, engines and search language -via the search query. - -Prefix ``!`` - to set Category/engine - -Prefix: ``:`` - to set language - -Abbrevations of the engines and languages are also accepted. Engine/category -modifiers are chainable and inclusive (e.g. with :search:`!it !ddg !wp qwer -` search in IT category **and** duckduckgo -**and** wikipedia for ``qwer``). - -See the :search:`/preferences page ` for the list of engines, -categories and languages. - -Examples -======== - -Search in wikipedia for ``qwer``: - -- :search:`!wp qwer ` or -- :search:`!wikipedia qwer :search:` - -Image search: - -- :search:`!images Cthulhu ` - -Custom language in wikipedia: - -- :search:`:hu !wp hackerspace ` -- cgit v1.2.3 From 8751940169378d89a3151df57a40d6ada21f035c Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 12 Mar 2022 10:54:30 +0100 Subject: [interim fix] of sphinx-tabs and sphinx-jinja The myst-parser requires >= docutils v.0.17 what ends in a dependency hell where plugins sphinx-tabs and sphinx-jinja we use are involved. This patch can be reverted when [2], [3], [4] are solved and new release is available / see [1]. [1] https://github.com/searxng/searxng/pull/954 [2] https://github.com/executablebooks/sphinx-tabs/issues/152 [3] https://github.com/executablebooks/sphinx-tabs/pull/153 [4] https://github.com/executablebooks/sphinx-tabs/pull/154 Signed-off-by: Markus Heiser --- docs/_themes/searxng/static/searxng.css | 2 +- docs/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/_themes/searxng/static/searxng.css b/docs/_themes/searxng/static/searxng.css index 64f6d4700..1ab8489ec 100644 --- a/docs/_themes/searxng/static/searxng.css +++ b/docs/_themes/searxng/static/searxng.css @@ -14,7 +14,7 @@ p.version-warning { background-color: #004b6b; } -div.sidebar { +aside.sidebar { background-color: whitesmoke; border-color: lightsteelblue; border-radius: 3pt; diff --git a/docs/conf.py b/docs/conf.py index 89d6bb8f6..1dd5693ca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,7 +116,7 @@ extensions = [ "sphinx.ext.intersphinx", "pallets_sphinx_themes", "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst - "sphinxcontrib.jinja", # https://github.com/tardyp/sphinx-jinja + "sphinx_jinja", # https://github.com/tardyp/sphinx-jinja "sphinxcontrib.programoutput", # https://github.com/NextThought/sphinxcontrib-programoutput 'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive. 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. -- cgit v1.2.3