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/_themes/searx_theme/layout.html | 20 ++ docs/_themes/searx_theme/relations.html | 15 + docs/_themes/searx_theme/static/style.css_t | 441 ++++++++++++++++++++++++++++ docs/_themes/searx_theme/theme.conf | 7 + docs/conf.py | 358 ++++++++++++++++++++++ docs/dev/contribution_guide.rst | 71 +++++ docs/dev/install/installation.rst | 277 +++++++++++++++++ docs/dev/plugins.rst | 45 +++ docs/dev/search_api.rst | 24 ++ docs/dev/translation.rst | 74 +++++ docs/index.rst | 39 +++ docs/static/img/searx_logo_small.png | Bin 0 -> 6472 bytes docs/user/search_syntax.rst | 33 +++ 13 files changed, 1404 insertions(+) create mode 100644 docs/_themes/searx_theme/layout.html create mode 100644 docs/_themes/searx_theme/relations.html create mode 100644 docs/_themes/searx_theme/static/style.css_t create mode 100644 docs/_themes/searx_theme/theme.conf create mode 100644 docs/conf.py create mode 100644 docs/dev/contribution_guide.rst create mode 100644 docs/dev/install/installation.rst create mode 100644 docs/dev/plugins.rst create mode 100644 docs/dev/search_api.rst create mode 100644 docs/dev/translation.rst create mode 100644 docs/index.rst create mode 100644 docs/static/img/searx_logo_small.png create mode 100644 docs/user/search_syntax.rst (limited to 'docs') diff --git a/docs/_themes/searx_theme/layout.html b/docs/_themes/searx_theme/layout.html new file mode 100644 index 000000000..edf70c1a8 --- /dev/null +++ b/docs/_themes/searx_theme/layout.html @@ -0,0 +1,20 @@ +{%- extends "basic/layout.html" %} +{%- block extrahead %} + {{ super() }} + {% if theme_touch_icon %} + + {% endif %} + + +{% endblock %} +{%- block relbar2 %}{% endblock %} +{%- block relbar1 %}{% endblock %} +{%- block sidebarsearch %}{% endblock %} +{%- block sidebarsourcelink %}{% endblock %} +{%- block sidebartoc %}{% endblock %} +{%- block footer %} +
+ © Copyright {{ copyright }}. +
+{%- endblock %} diff --git a/docs/_themes/searx_theme/relations.html b/docs/_themes/searx_theme/relations.html new file mode 100644 index 000000000..13cfa019d --- /dev/null +++ b/docs/_themes/searx_theme/relations.html @@ -0,0 +1,15 @@ +
+

Searx

+ +
+ +
diff --git a/docs/_themes/searx_theme/static/style.css_t b/docs/_themes/searx_theme/static/style.css_t new file mode 100644 index 000000000..4a266671f --- /dev/null +++ b/docs/_themes/searx_theme/static/style.css_t @@ -0,0 +1,441 @@ +/* + * flasky.css_t + * ~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. + * :license: Flask Design License, see LICENSE for details. + */ + +{% set page_width = '940px' %} +{% set sidebar_width = '220px' %} + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; + font-size: 17px; + background-color: white; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + width: {{ page_width }}; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ sidebar_width }}; +} + +div.sphinxsidebar { + width: {{ sidebar_width }}; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + width: {{ page_width }}; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebarwrapper { + padding: 0 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 -20px; + text-align: center; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: 'Garamond', 'Georgia', serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: 'Georgia', serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #eaeaea; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; + background: #fdfdfd; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td.label { + width: 0px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #eee; + padding: 7px 30px; + margin: 15px -30px; + line-height: 1.3em; +} + +dl pre, blockquote pre, li pre { + margin-left: -60px; + padding-left: 60px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid white; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt { + background: #EEE; +} + + +@media screen and (max-width: 600px) { + + div.document { + width: 100%; + + } + + div.documentwrapper { + margin-left: 0; + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + } + + div.bodywrapper { + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + margin-left: 0; + } + + ul { + margin-left: 0; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .bodywrapper { + margin: 0; + } + + .footer { + width: auto; + } + + div.sphinxsidebar { + display: none; + } + +} + +div.sidebar_container, div.sidebar_container h1 { +} + +div.sidebar_container h1 { + padding: 0; + margin: 0; + font-size: 350%; + line-height: 100%; +} + +div.sidebar_container ul li { + padding: 2px 8px; + font-size: 0.9em; +} diff --git a/docs/_themes/searx_theme/theme.conf b/docs/_themes/searx_theme/theme.conf new file mode 100644 index 000000000..38f9aaa93 --- /dev/null +++ b/docs/_themes/searx_theme/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = basic +stylesheet = style.css +pygments_style = flask_theme_support.FlaskyStyle + +[options] +touch_icon = diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..30fe90313 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,358 @@ +# -*- coding: utf-8 -*- +# +# searx documentation build configuration file, created by +# sphinx-quickstart on Tue Nov 17 17:12:13 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'searx' +copyright = u'2015, Adam Tauber' +author = u'Adam Tauber' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.8.0' +# The full version, including alpha/beta/rc tags. +release = '0.8.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +sys.path.append(os.path.abspath('_themes')) +html_theme_path = ['_themes'] +html_theme = 'searx_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'searxdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'searx.tex', u'searx Documentation', + u'Adam Tauber', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'searx', u'searx Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'searx', u'searx Documentation', + author, 'searx', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not optimized +# for small screen space, using the same theme for HTML and epub output is +# usually not wise. This defaults to 'epub', a theme designed to save visual +# space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst new file mode 100644 index 000000000..5685549eb --- /dev/null +++ b/docs/dev/contribution_guide.rst @@ -0,0 +1,71 @@ +How to contribute +----------------- + +Prime directives: Privacy, Hackability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Searx has 2 prime directives, privacy-by-design and hackability. The +hackability comes in at least 3 levels: + +- support for search engines +- plugins for altering search behaviour +- hacking searx itself. + +Happy hacking. Observe the lack of "world domination" among the +directives, searx has no intentions for wide mass-adoption, rounded +corners, etc. The prime directive: "privacy" - deserves a seperate +chapter, as it's quite uncommon unfortunately, here it goes: + +Privacy-by-design +^^^^^^^^^^^^^^^^^ + +Searx is a privacy-respecting, hackable meta-search engine. It was born +out of the need for a privacy-respecing search facility that can be +expanded easily to maximise both its search and it's privacy protecting +capabilities. + +Consequences of Privacy-by-design are that some widely used features +work differently or not by default or at all. If some feature reduces +the privacy perserving aspects of searx, it should by default be +switched of, if implemented at all. There is enough search engines +already out there providing such features. = Since privacy-preservation +is a prime goal, if some feature does reduce the protection of searx and +is implemented, care should be taken to educate the user about the +consequences of choosing to enable this. Further features which +implement widely known features in a manner that protects privacy but +thus deviate from the users expectations should also be explained to the +user. Also if you think that something works weird with searx, maybe +it's because of the tool you use is designed in a way to interfere with +privacy respect, submiting a bugreport to the vendor of the tool that +misbehaves might be a good feedback for the vendor to reconsider his +disrespect towards his customers (e.g. GET vs POST requests in various +browsers). + +Remember the other prime directive of searx is to be hackable, so if the +above privacy concerns do not fancy you, simply fork it. + +Code +~~~~ + +Code modifications are accepted in pull requests, don't forget to add +yourself to the AUTHORS file. + +Python code follows all the pep8 standards except maximum line width +which is 120 char. + +Please be sure that the submitted code doesn't break existing tests and +follows coding conventions. + +If new functionality implemented, tests are highly appreciated. + +Translation +~~~~~~~~~~~ + +Translation currently happens on +`transifex `__. Please do not +update translation files in the repo. + +Documentation +~~~~~~~~~~~~~ + +The main place of the documentation is this wiki, updates are welcome. diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst new file mode 100644 index 000000000..2ce6a6b54 --- /dev/null +++ b/docs/dev/install/installation.rst @@ -0,0 +1,277 @@ +Installation +============ + +Step by step installation for Debian / Ubuntu with virtualenv. + +Source: https://about.okhin.fr/posts/Searx/ with some additions + +How to: `Setup searx in a couple of hours with a free SSL +certificate `__ + +Basic installation +------------------ + +For Ubuntu, be sure to have enable universe repository. + +Install packages : + +.. code:: sh + + sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-pybabel zlib1g-dev libffi-dev libssl-dev + +Install searx : + +.. code:: sh + + cd /usr/local + sudo git clone https://github.com/asciimoo/searx.git + sudo useradd searx -d /usr/local/searx + sudo chown searx:searx -R /usr/local/searx + +Install dependencies in a virtualenv : + +.. code:: sh + + sudo -u searx -i + cd /usr/local/searx + virtualenv searx-ve + . ./searx-ve/bin/activate + pip install -r requirements.txt + python setup.py install + +Configuration +------------- + +.. code:: sh + + sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml + +Edit searx/settings.yml if necessary. + +Check +----- + +Start searx : + +.. code:: sh + + python searx/webapp.py + +Go to http://localhost:8888 + +If everything works fine, disable the debug option in settings.yml : + +.. code:: sh + + sed -i -e "s/debug : True/debug : False/g" searx/settings.yml + +At this point searx is not demonized ; uwsgi allows this. + +You can exit the virtualenv and the searx user bash (enter exit command +twice). + +uwsgi +----- + +Install packages : + +.. code:: sh + + sudo apt-get install uwsgi uwsgi-plugin-python + +Create the configuration file /etc/uwsgi/apps-available/searx.ini with +this content : + +:: + + [uwsgi] + # Who will run the code + uid = searx + gid = searx + + # disable logging for privacy + disable-logging = true + + # Number of workers (usually CPU count) + workers = 4 + + # The right granted on the created socket + chmod-socket = 666 + + # Plugin to use and interpretor config + single-interpreter = true + master = true + plugin = python + + # Module to import + module = searx.webapp + + # Virtualenv and python path + virtualenv = /usr/local/searx/searx-ve/ + pythonpath = /usr/local/searx/ + chdir = /usr/local/searx/searx/ + +Activate the uwsgi application and restart : + +.. code:: sh + + cd /etc/uwsgi/apps-enabled + ln -s ../apps-available/searx.ini + /etc/init.d/uwsgi restart + +Web server +---------- + +with nginx +^^^^^^^^^^ + +If nginx is not installed (uwsgi will not work with the package +nginx-light) : + +.. code:: sh + + sudo apt-get install nginx + +Hosted at / +""""""""""" + +Create the configuration file /etc/nginx/sites-available/searx with this +content : + +.. code:: nginx + + server { + listen 80; + server_name searx.example.com; + root /usr/local/searx; + + location / { + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app/searx/socket; + } + } + +Restart service : + +.. code:: sh + + sudo service nginx restart + sudo service uwsgi restart + +from subdirectory URL (/searx) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add this configuration in the server config file +/etc/nginx/sites-available/default : + +.. code:: nginx + + location = /searx { rewrite ^ /searx/; } + location /searx { + try_files $uri @searx; + } + location @searx { + uwsgi_param SCRIPT_NAME /searx; + include uwsgi_params; + uwsgi_modifier1 30; + uwsgi_pass unix:/run/uwsgi/app/searx/socket; + } + +Enable base\_url in searx/settings.yml + +:: + + base_url : http://your.domain.tld/searx/ + +Restart service : + +.. code:: sh + + sudo service nginx restart + sudo service uwsgi restart + +disable logs +~~~~~~~~~~~~ + +for better privacy you can disable nginx logs about searx. + +how to proceed : below ``uwsgi_pass`` in +/etc/nginx/sites-available/default add + +:: + + access_log /dev/null; + error_log /dev/null; + +Restart service : + +.. code:: sh + + sudo service nginx restart + +with apache +----------- + +Add wsgi mod : + +.. code:: sh + + sudo apt-get install libapache2-mod-uwsgi + sudo a2enmod uwsgi + +Add this configuration in the file /etc/apache2/apache2.conf : + +.. code:: apache + + + Options FollowSymLinks Indexes + SetHandler uwsgi-handler + uWSGISocket /run/uwsgi/app/searx/socket + + +Note that if your instance of searx is not at the root, you should +change ```` by the location of your instance, like +````. + +Restart Apache : + +.. code:: sh + + sudo /etc/init.d/apache2 restart + +disable logs +------------ + +For better privacy you can disable Apache logs. + +WARNING : not tested + +WARNING : you can only disable logs for the whole (virtual) server not +for a specific path. + +Go back to /etc/apache2/apache2.conf and above ```` add : + +.. code:: apache + + CustomLog /dev/null combined + +Restart Apache : + +.. code:: sh + + sudo /etc/init.d/apache2 restart + +How to update +------------- + +.. code:: sh + + cd /usr/local/searx + sudo -u searx -i + . ./searx-ve/bin/activate + git stash + git pull origin master + git stash apply + pip install --upgrade -r requirements.txt + sudo service uwsgi restart + diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst new file mode 100644 index 000000000..c51fdf0eb --- /dev/null +++ b/docs/dev/plugins.rst @@ -0,0 +1,45 @@ +Plugins +------- + +Plugins can extend/replace functionality of various components inside +searx. + +example\_plugin.py +~~~~~~~~~~~~~~~~~~ + +.. code:: python + + name = 'Example plugin' + description = 'This plugin extends the suggestions with the word "example"' + default_on = False # disable by default + + js_dependencies = tuple() # optional, list of static js files + css_dependencies = tuple() # optional, list of static css files + + + # attach callback to the post search hook + # request: flask request object + # ctx: the whole local context of the post search hook + def post_search(request, ctx): + ctx['search'].suggestions.add('example') + return True + +Currently implemented plugin entry points (a.k.a hooks) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Pre search hook (``pre_search``) +- Post search hook (``post_search``) +- Result hook (``on_result``) (is called if a new result is added (see + https\_rewrite plugin)) + +Feel free to add more hooks to the code if it is required by a plugin. + +TODO +~~~~ + +- Better documentation +- More hooks +- search hook (is called while searx is requesting results (for + example: things like math-solver), the different hooks are running + parallel) + 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. diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst new file mode 100644 index 000000000..0fc02a7de --- /dev/null +++ b/docs/dev/translation.rst @@ -0,0 +1,74 @@ +Translation +=========== + +run these commands in the root directory of searx + +Add new language +~~~~~~~~~~~~~~~~ + +``pybabel init -i messages.pot -d searx/translations -l it`` + +Update .po files +~~~~~~~~~~~~~~~~ + +``./utils/update-translations.sh`` + +You may have errors here. In that case, edit the +``update-translations.sh`` script to change ``pybabel`` to +``pybabel-python2`` + +After this step, you can modify the .po files. + +Compile translations +~~~~~~~~~~~~~~~~~~~~ + +``pybabel compile -d searx/translations`` + +Transifex stuff +~~~~~~~~~~~~~~~ + +Init Project +^^^^^^^^^^^^ + +.. code:: shell + + tx set --auto-local -r searx.messagespo 'searx/translations//LC_MESSAGES/messages.po' \ + --source-lang en --type PO --source-file messages.pot --execute + +http://docs.transifex.com/developer/client/set + +*TODO: mapping between transifex and searx* + +Get translations +^^^^^^^^^^^^^^^^ + +.. code:: shell + + tx pull -a + +http://docs.transifex.com/developer/client/pull + +Upload source File +^^^^^^^^^^^^^^^^^^ + +:: + + tx push -s + +Upload all Translation +^^^^^^^^^^^^^^^^^^^^^^ + +:: + + tx push -s -t + +upload specifc Translation (only for admins) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + tx push -t -l tr + +http://docs.transifex.com/developer/client/push + +*TODO: upload empty files? (new translations)* diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..abb620627 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,39 @@ +Privacy-respecting free metasearch engine +========================================= + +Searx is a free software internet metasearch engine which aggregates results from other search engines, while not storing information about its users. Searx does not track or profile its users, nor does it share its users' data with third parties. Additionally, searx can be used over Tor for online anonymity. + + +Features +-------- + + - Self hosted + - Does not track its users + - Does not share its users data with third parties + - Does not use cookies by default + - Does not profile its users + - Does not collect its users data + - Offers secure, encrypted connections (HTTPS/SSL) + - Hosted by organisations, such as La Quadrature du Net, which promote digital rights + + +Further reading +--------------- + +.. toctree:: + :maxdepth: 1 + + user/search_syntax + + +Developer documentation +----------------------- + +.. toctree:: + :maxdepth: 1 + + dev/contribution_guide + dev/install/installation + dev/search_api + dev/plugins + dev/translation diff --git a/docs/static/img/searx_logo_small.png b/docs/static/img/searx_logo_small.png new file mode 100644 index 000000000..083932686 Binary files /dev/null and b/docs/static/img/searx_logo_small.png differ diff --git a/docs/user/search_syntax.rst b/docs/user/search_syntax.rst new file mode 100644 index 000000000..af26ea83c --- /dev/null +++ b/docs/user/search_syntax.rst @@ -0,0 +1,33 @@ +Search syntax +============= + +Searx allows you to modify the default categories, engines and search +language via the search query. + +Category/engine prefix: ``!`` + +Language prefix: ``:`` + +Prefix to add engines and categories to the currently selected +categories: ``?`` + +Abbrevations of the engines and languages are also accepted. +Engine/category modifiers are chainable and inclusive (e.g. with +`!it !ddg !wp qwer `_ +search in IT category **and** duckduckgo **and** wikipedia for ``qwer``). + +See the `/preferences page `_ for the +list of engines, categories and languages. + +Examples +~~~~~~~~ + +Search in wikipedia for ``qwer``: +`!wp qwer `__ or +`!wikipedia qwer `_ + +Image search: +`!images Cthulhu `_ + +Custom language in wikipedia: +`:hu !wp hackerspace `_ -- cgit v1.2.3 From 11d6d80d8831459161ac08ad0587ab8775ffd3e3 Mon Sep 17 00:00:00 2001 From: Adam Tauber Date: Sat, 28 Nov 2015 19:26:45 +0100 Subject: [doc] engines overview added --- docs/dev/engine_overview.rst | 314 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 315 insertions(+) create mode 100644 docs/dev/engine_overview.rst (limited to 'docs') diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst new file mode 100644 index 000000000..7f170e9d6 --- /dev/null +++ b/docs/dev/engine_overview.rst @@ -0,0 +1,314 @@ +Engine overview +=============== + + +searx is a `metasearch-engine `__, +so it is using different search engines to provide better results. + +Because there is no general search-api which can be used for every +search-engine, there must be build an adapter between searx and the +external search-engine. This adapters are stored in the folder +`*searx/engines* `__, +and this site is build to make an general documentation about this +engines + + +.. contents:: + :depth: 3 + +general engine configuration +---------------------------- + +It is required to tell searx what results can the engine provide. The +arguments can be inserted in the engine file, or in the settings file +(normally ``settings.yml``). The arguments in the settings file override +the one in the engine file. + +Really, it is for most options no difference if there are contained in +the engine-file or in the settings. But there is a standard where to +place specific arguments by default. + + +engine-file +~~~~~~~~~~~ + ++---------------------+-----------+-----------------------------------------+ +| argument | type | information | ++=====================+===========+=========================================+ +| categories | list | pages, in which the engine is working | ++---------------------+-----------+-----------------------------------------+ +| paging | boolean | support multible pages | ++---------------------+-----------+-----------------------------------------+ +| language\_support | boolean | support language choosing | ++---------------------+-----------+-----------------------------------------+ + +settings.yml +~~~~~~~~~~~~ + ++------------+----------+-----------------------------------------------+ +| argument | type | information | ++============+==========+===============================================+ +| name | string | name of search-engine | ++------------+----------+-----------------------------------------------+ +| engine | string | name of searx-engine (filename without .py) | ++------------+----------+-----------------------------------------------+ +| shortcut | string | shortcut of search-engine | ++------------+----------+-----------------------------------------------+ +| timeout | string | specific timeout for search-engine | ++------------+----------+-----------------------------------------------+ + +overrides +~~~~~~~~~ + +There are some options, with have default values in the engine, but are +often overwritten by the settings. If the option is assigned in the +engine-file with ``None`` it has to be redefined in the settings, +otherwise searx is not starting with that engine. + +The naming of that overrides can be wathever you want. But we recommend +the using of already used overrides if possible: + ++-----------------------+----------+--------------------------------------------------------------+ +| argument | type | information | ++=======================+==========+==============================================================+ +| base\_url | string | base-url, can be overwrite to use same engine on other url | ++-----------------------+----------+--------------------------------------------------------------+ +| number\_of\_results | int | maximum number of results per request | ++-----------------------+----------+--------------------------------------------------------------+ +| language | string | ISO code of language and country like en\_US | ++-----------------------+----------+--------------------------------------------------------------+ +| api\_key | string | api-key if required by engine | ++-----------------------+----------+--------------------------------------------------------------+ + +example-code +~~~~~~~~~~~~ + +.. code:: python + + # engine dependent config + categories = ['general'] + paging = True + language_support = True + +doing request +------------- + +To perform a search you have to specific at least a url on which the +request is performing + +passed arguments +~~~~~~~~~~~~~~~~ + +This arguments can be used to calculate the search-query. Furthermore, +some of that parameters are filled with default values which can be +changed for special purpose. + ++----------------------+------------+------------------------------------------------------------------------+ +| argument | type | default-value, informations | ++======================+============+========================================================================+ +| url | string | ``''`` | ++----------------------+------------+------------------------------------------------------------------------+ +| method | string | ``'GET'`` | ++----------------------+------------+------------------------------------------------------------------------+ +| headers | set | ``{}`` | ++----------------------+------------+------------------------------------------------------------------------+ +| data | set | ``{}`` | ++----------------------+------------+------------------------------------------------------------------------+ +| cookies | set | ``{}`` | ++----------------------+------------+------------------------------------------------------------------------+ +| verify | boolean | ``True`` | ++----------------------+------------+------------------------------------------------------------------------+ +| headers.User-Agent | string | a random User-Agent | ++----------------------+------------+------------------------------------------------------------------------+ +| category | string | current category, like ``'general'`` | ++----------------------+------------+------------------------------------------------------------------------+ +| started | datetime | current date-time | ++----------------------+------------+------------------------------------------------------------------------+ +| pageno | int | current pagenumber | ++----------------------+------------+------------------------------------------------------------------------+ +| language | string | specific language code like ``'en_US'``, or ``'all'`` if unspecified | ++----------------------+------------+------------------------------------------------------------------------+ + +parsed arguments +~~~~~~~~~~~~~~~~ + +The function ``def request(query, params):`` is always returning the +``params`` variable back. Inside searx, the following paramters can be +used to specific a search-request: + ++------------+-----------+----------------------------------------------------------+ +| argument | type | information | ++============+===========+==========================================================+ +| url | string | requested url | ++------------+-----------+----------------------------------------------------------+ +| method | string | HTTP request methode | ++------------+-----------+----------------------------------------------------------+ +| headers | set | HTTP header informations | ++------------+-----------+----------------------------------------------------------+ +| data | set | HTTP data informations (parsed if ``method != 'GET'``) | ++------------+-----------+----------------------------------------------------------+ +| cookies | set | HTTP cookies | ++------------+-----------+----------------------------------------------------------+ +| verify | boolean | Performing SSL-Validity check | ++------------+-----------+----------------------------------------------------------+ + +example-code +~~~~~~~~~~~~ + +.. code:: python + + # search-url + base_url = 'https://example.com/' + search_string = 'search?{query}&page={page}' + + # do search-request + def request(query, params): + search_path = search_string.format( + query=urlencode({'q': query}), + page=params['pageno']) + + params['url'] = base_url + search_path + + return params + +returning results +----------------- + +Searx has the possiblity to return results in different media-types. +Currently the following media-types are supported: + +- default +- images +- videos +- torrent +- map + +to set another media-type as default, you must set the parameter +``template`` to the required type. + +default +~~~~~~~ + ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+====================================================================================================================================+ +| url | string, which is representing the url of the result | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| content | string, which is giving a general result-text | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, represent when the result is published | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ + +images +~~~~~~ + +to use this template, the parameter + ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+===========================================================================================================================================================+ +| template | is set to ``images.html`` | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, which is representing the url to the result site | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result *(partly implemented)* | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| content | *(partly implemented)* | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, represent when the result is published *(partly implemented)* | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| img\_src | string, which is representing the url to the result image | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| thumbnail\_src | string, which is representing the url to a small-preview image | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ + +videos +~~~~~~ + ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+====================================================================================================================================+ +| template | is set to ``videos.html`` | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, which is representing the url of the result | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| content | *(not implemented yet)* | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, represent when the result is published | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| thumbnail | string, which is representing the url to a small-preview image | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------+ + +torrent +~~~~~~~ + ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| template | is set to ```torrent.html``` | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, which is representing the url of the result | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| content | string, which is giving a general result-text | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | [datetime.datetime](https://docs.python.org/2/library/datetime.html#datetime-objects), represent when the result is published _(not implemented yet)_ | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| seed | int, number of seeder | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| leech | int, number of leecher | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| filesize | int, size of file in bytes | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| files | int, number of files | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| magnetlink | string, which is the [magnetlink](https://en.wikipedia.org/wiki/Magnet_URI_scheme) of the result | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| torrentfile | string, which is the torrentfile of the result | ++------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +map +~~~ + ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++=========================+====================================================================================================================================+ +| url | string, which is representing the url of the result | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| content | string, which is giving a general result-text | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, represent when the result is published | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| latitude | latitude of result (in decimal format) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| longitude | longitude of result (in decimal format) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| boundingbox | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| geojson | geojson of result (http://geojson.org) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| osm.type | type of osm-object (if OSM-Result) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| osm.id | id of osm-object (if OSM-Result) | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.name | name of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.road | street adress of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.house\_number | house number of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.locality | city, place of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.postcode | postcode of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| address.country | country of object | ++-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ + diff --git a/docs/index.rst b/docs/index.rst index abb620627..09dd1798d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,6 +34,7 @@ Developer documentation dev/contribution_guide dev/install/installation + dev/engine_overview dev/search_api dev/plugins dev/translation -- cgit v1.2.3 From ae69a58089cc195d211cd195c79cd60bb49a474f Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Tue, 1 Dec 2015 15:32:06 +0100 Subject: [doc] grammar & format fixes in engine overview --- docs/dev/engine_overview.rst | 185 +++++++++++++++++++++---------------------- 1 file changed, 91 insertions(+), 94 deletions(-) (limited to 'docs') diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 7f170e9d6..05a54b641 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -3,14 +3,13 @@ Engine overview searx is a `metasearch-engine `__, -so it is using different search engines to provide better results. +so it uses different search engines to provide better results. -Because there is no general search-api which can be used for every -search-engine, there must be build an adapter between searx and the -external search-engine. This adapters are stored in the folder -`*searx/engines* `__, -and this site is build to make an general documentation about this -engines +Because there is no general search API which could be used for every +search engine, an adapter has to be built between searx and the +external search engines. Adapters are stored under the folder +`searx/engines +`__. .. contents:: @@ -19,17 +18,16 @@ engines general engine configuration ---------------------------- -It is required to tell searx what results can the engine provide. The -arguments can be inserted in the engine file, or in the settings file +It is required to tell searx the type of results the engine provides. The +arguments can be set in the engine file or in the settings file (normally ``settings.yml``). The arguments in the settings file override -the one in the engine file. +the ones in the engine file. -Really, it is for most options no difference if there are contained in -the engine-file or in the settings. But there is a standard where to -place specific arguments by default. +It does not matter if an options is stored in the engine file or in the +settings. However, the standard way is the following: -engine-file +engine file ~~~~~~~~~~~ +---------------------+-----------+-----------------------------------------+ @@ -60,27 +58,27 @@ settings.yml overrides ~~~~~~~~~ -There are some options, with have default values in the engine, but are -often overwritten by the settings. If the option is assigned in the -engine-file with ``None`` it has to be redefined in the settings, -otherwise searx is not starting with that engine. - -The naming of that overrides can be wathever you want. But we recommend -the using of already used overrides if possible: - -+-----------------------+----------+--------------------------------------------------------------+ -| argument | type | information | -+=======================+==========+==============================================================+ -| base\_url | string | base-url, can be overwrite to use same engine on other url | -+-----------------------+----------+--------------------------------------------------------------+ -| number\_of\_results | int | maximum number of results per request | -+-----------------------+----------+--------------------------------------------------------------+ -| language | string | ISO code of language and country like en\_US | -+-----------------------+----------+--------------------------------------------------------------+ -| api\_key | string | api-key if required by engine | -+-----------------------+----------+--------------------------------------------------------------+ - -example-code +A few of the options have default values in the engine, but are +often overwritten by the settings. If ``None`` is assigned to an option +in the engine file, it has to be redefined in the settings, +otherwise searx will not start with that engine. + +The naming of that overrides is arbitrary. But the recommended +overrides are the following: + ++-----------------------+----------+----------------------------------------------------------------+ +| argument | type | information | ++=======================+==========+================================================================+ +| base\_url | string | base-url, can be overwritten to use same engine on other URL | ++-----------------------+----------+----------------------------------------------------------------+ +| number\_of\_results | int | maximum number of results per request | ++-----------------------+----------+----------------------------------------------------------------+ +| language | string | ISO code of language and country like en\_US | ++-----------------------+----------+----------------------------------------------------------------+ +| api\_key | string | api-key if required by engine | ++-----------------------+----------+----------------------------------------------------------------+ + +example code ~~~~~~~~~~~~ .. code:: python @@ -90,21 +88,20 @@ example-code paging = True language_support = True -doing request -------------- +making a request +---------------- -To perform a search you have to specific at least a url on which the -request is performing +To perform a search an URL have to be specified. In addition to +specifying an URL, arguments can be passed to the query. passed arguments ~~~~~~~~~~~~~~~~ -This arguments can be used to calculate the search-query. Furthermore, -some of that parameters are filled with default values which can be -changed for special purpose. +These arguments can be used to construct the search query. Furthermore, +parameters with default value can be redefined for special purposes. +----------------------+------------+------------------------------------------------------------------------+ -| argument | type | default-value, informations | +| argument | type | default-value, information | +======================+============+========================================================================+ | url | string | ``''`` | +----------------------+------------+------------------------------------------------------------------------+ @@ -132,27 +129,27 @@ changed for special purpose. parsed arguments ~~~~~~~~~~~~~~~~ -The function ``def request(query, params):`` is always returning the -``params`` variable back. Inside searx, the following paramters can be -used to specific a search-request: - -+------------+-----------+----------------------------------------------------------+ -| argument | type | information | -+============+===========+==========================================================+ -| url | string | requested url | -+------------+-----------+----------------------------------------------------------+ -| method | string | HTTP request methode | -+------------+-----------+----------------------------------------------------------+ -| headers | set | HTTP header informations | -+------------+-----------+----------------------------------------------------------+ -| data | set | HTTP data informations (parsed if ``method != 'GET'``) | -+------------+-----------+----------------------------------------------------------+ -| cookies | set | HTTP cookies | -+------------+-----------+----------------------------------------------------------+ -| verify | boolean | Performing SSL-Validity check | -+------------+-----------+----------------------------------------------------------+ - -example-code +The function ``def request(query, params):`` always returns the +``params`` variable. Inside searx, the following paramters can be +used to specify a search request: + ++------------+-----------+---------------------------------------------------------+ +| argument | type | information | ++============+===========+=========================================================+ +| url | string | requested url | ++------------+-----------+---------------------------------------------------------+ +| method | string | HTTP request method | ++------------+-----------+---------------------------------------------------------+ +| headers | set | HTTP header information | ++------------+-----------+---------------------------------------------------------+ +| data | set | HTTP data information (parsed if ``method != 'GET'``) | ++------------+-----------+---------------------------------------------------------+ +| cookies | set | HTTP cookies | ++------------+-----------+---------------------------------------------------------+ +| verify | boolean | Performing SSL-Validity check | ++------------+-----------+---------------------------------------------------------+ + +example code ~~~~~~~~~~~~ .. code:: python @@ -171,10 +168,10 @@ example-code return params -returning results ------------------ +returned results +---------------- -Searx has the possiblity to return results in different media-types. +Searx is able to return results of different media-types. Currently the following media-types are supported: - default @@ -183,8 +180,8 @@ Currently the following media-types are supported: - torrent - map -to set another media-type as default, you must set the parameter -``template`` to the required type. +To set another media-type as default, the parameter +``template`` must be set to the desired type. default ~~~~~~~ @@ -246,31 +243,31 @@ videos torrent ~~~~~~~ -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| template | is set to ```torrent.html``` | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, which is representing the url of the result | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| content | string, which is giving a general result-text | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | [datetime.datetime](https://docs.python.org/2/library/datetime.html#datetime-objects), represent when the result is published _(not implemented yet)_ | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| seed | int, number of seeder | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| leech | int, number of leecher | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| filesize | int, size of file in bytes | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| files | int, number of files | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| magnetlink | string, which is the [magnetlink](https://en.wikipedia.org/wiki/Magnet_URI_scheme) of the result | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ -| torrentfile | string, which is the torrentfile of the result | -+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| template | is set to ```torrent.html``` | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, which is representing the url of the result | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, which is representing the title of the result | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| content | string, which is giving a general result-text | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, represent when the result is published *(not implemented yet)* | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| seed | int, number of seeder | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| leech | int, number of leecher | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| filesize | int, size of file in bytes | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| files | int, number of files | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| magnetlink | string, which is the `magnetlink `__ of the result | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| torrentfile | string, which is the torrentfile of the result | ++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ map -- cgit v1.2.3 From 240802003ee98e93e084788665445d81a9623c7d Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 10 Dec 2015 21:38:39 +0100 Subject: [doc] fix small mistakes in engine overview --- docs/dev/engine_overview.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 05a54b641..186cc0f94 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -23,7 +23,7 @@ arguments can be set in the engine file or in the settings file (normally ``settings.yml``). The arguments in the settings file override the ones in the engine file. -It does not matter if an options is stored in the engine file or in the +It does not matter if an option is stored in the engine file or in the settings. However, the standard way is the following: @@ -63,7 +63,7 @@ often overwritten by the settings. If ``None`` is assigned to an option in the engine file, it has to be redefined in the settings, otherwise searx will not start with that engine. -The naming of that overrides is arbitrary. But the recommended +The naming of overrides is arbitrary. But the recommended overrides are the following: +-----------------------+----------+----------------------------------------------------------------+ -- cgit v1.2.3 From 3b068141928c17b6bb7b343d6e926fc3c443a022 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 10 Dec 2015 21:40:22 +0100 Subject: [doc] rewrite contribution guide --- docs/dev/contribution_guide.rst | 107 +++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 41 deletions(-) (limited to 'docs') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 5685549eb..73f4ea332 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -4,68 +4,93 @@ How to contribute Prime directives: Privacy, Hackability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Searx has 2 prime directives, privacy-by-design and hackability. The -hackability comes in at least 3 levels: +Searx has two prime directives, privacy-by-design and hackability. The +hackability comes in three levels: -- support for search engines -- plugins for altering search behaviour -- hacking searx itself. +- support of search engines +- plugins to alter search behaviour +- hacking searx itself -Happy hacking. Observe the lack of "world domination" among the -directives, searx has no intentions for wide mass-adoption, rounded -corners, etc. The prime directive: "privacy" - deserves a seperate -chapter, as it's quite uncommon unfortunately, here it goes: +Note the lack of "world domination" among the directives. +Searx has no intention of wide mass-adoption, rounded +corners, etc. The prime directive "privacy" deserves a separate +chapter, as it's quite uncommon unfortunately. Privacy-by-design ^^^^^^^^^^^^^^^^^ -Searx is a privacy-respecting, hackable meta-search engine. It was born -out of the need for a privacy-respecing search facility that can be -expanded easily to maximise both its search and it's privacy protecting -capabilities. - -Consequences of Privacy-by-design are that some widely used features -work differently or not by default or at all. If some feature reduces -the privacy perserving aspects of searx, it should by default be -switched of, if implemented at all. There is enough search engines -already out there providing such features. = Since privacy-preservation -is a prime goal, if some feature does reduce the protection of searx and -is implemented, care should be taken to educate the user about the -consequences of choosing to enable this. Further features which -implement widely known features in a manner that protects privacy but -thus deviate from the users expectations should also be explained to the -user. Also if you think that something works weird with searx, maybe -it's because of the tool you use is designed in a way to interfere with -privacy respect, submiting a bugreport to the vendor of the tool that -misbehaves might be a good feedback for the vendor to reconsider his -disrespect towards his customers (e.g. GET vs POST requests in various -browsers). +Searx was born out of the need for a privacy-respecting search tool +which can be extended easily to maximize both its search and its +privacy protecting capabilities. + +A few widely used features work differently or turned off by default or not implemented +at all as a consequence of privacy-by-design. + +If a feature reduces the privacy preserving aspects of searx, it +should be switched off by default or should not implemented at all. +There are plenty of search engines already providing such features. +If a feature reduces the protection of searx, users must be +informed about the effect of choosing to enable it. Features +that protect privacy but differ from the expectations of the +user should also be explained. + +Also, if you think that something works weird with searx, +it's might be because of the tool you use is designed in a way to interfere with +the privacy respect. Submitting a bugreport to the vendor of the tool that +misbehaves might be a good feedback to reconsider the disrespect to +its customers (e.g. GET vs POST requests in various browsers). Remember the other prime directive of searx is to be hackable, so if the above privacy concerns do not fancy you, simply fork it. +Happy hacking. + Code ~~~~ -Code modifications are accepted in pull requests, don't forget to add -yourself to the AUTHORS file. +In order to submit a patch, please follow the steps below: + +- Follow coding conventions. + + - PEP8 standards apply, except the convention of line length + + - Maximum line length is 120 characters + +- Check if your code breaks existing tests. If so, update the tests or fix your code. + +- If your code can be unit-tested, add unit tests. -Python code follows all the pep8 standards except maximum line width -which is 120 char. +- Add yourself to the AUTHORS file. -Please be sure that the submitted code doesn't break existing tests and -follows coding conventions. +- Create a pull request. -If new functionality implemented, tests are highly appreciated. Translation ~~~~~~~~~~~ -Translation currently happens on -`transifex `__. Please do not -update translation files in the repo. +Translation currently takes place on +`transifex `__. + +**Please, do not update translation files in the repo.** Documentation ~~~~~~~~~~~~~ -The main place of the documentation is this wiki, updates are welcome. +The documentation is built using Sphinx. So in order to be able to generate the required +files, you have to install it on your system. (It can be installed easily using pip.) + +1. Checkout the gh-pages branch. + +2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder. + +3. Build the documentation using Sphinx. + +4. Add the updated and created files of these extension: + + - .rst + + - .html + + - .txt + +6. Create a pull request. -- cgit v1.2.3 From 08d26609a5cffa1c70d6aa22cfa4455e1feb2002 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Sun, 10 Jan 2016 20:10:53 +0100 Subject: update & fix install guide after install refactor --- docs/dev/install/installation.rst | 81 +++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index 2ce6a6b54..e15ff8b25 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -1,25 +1,28 @@ Installation ============ -Step by step installation for Debian / Ubuntu with virtualenv. +Step by step installation for Debian/Ubuntu with virtualenv. Source: https://about.okhin.fr/posts/Searx/ with some additions How to: `Setup searx in a couple of hours with a free SSL certificate `__ +.. contents:: + :depth: 3 + Basic installation ------------------ For Ubuntu, be sure to have enable universe repository. -Install packages : +Install packages: .. code:: sh sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-pybabel zlib1g-dev libffi-dev libssl-dev -Install searx : +Install searx: .. code:: sh @@ -28,7 +31,7 @@ Install searx : sudo useradd searx -d /usr/local/searx sudo chown searx:searx -R /usr/local/searx -Install dependencies in a virtualenv : +Install dependencies in a virtualenv: .. code:: sh @@ -36,8 +39,7 @@ Install dependencies in a virtualenv : cd /usr/local/searx virtualenv searx-ve . ./searx-ve/bin/activate - pip install -r requirements.txt - python setup.py install + ./manage.sh update_packages Configuration ------------- @@ -51,7 +53,7 @@ Edit searx/settings.yml if necessary. Check ----- -Start searx : +Start searx: .. code:: sh @@ -59,7 +61,7 @@ Start searx : Go to http://localhost:8888 -If everything works fine, disable the debug option in settings.yml : +If everything works fine, disable the debug option in settings.yml: .. code:: sh @@ -73,14 +75,14 @@ twice). uwsgi ----- -Install packages : +Install packages: .. code:: sh sudo apt-get install uwsgi uwsgi-plugin-python Create the configuration file /etc/uwsgi/apps-available/searx.ini with -this content : +this content: :: @@ -111,7 +113,7 @@ this content : pythonpath = /usr/local/searx/ chdir = /usr/local/searx/searx/ -Activate the uwsgi application and restart : +Activate the uwsgi application and restart: .. code:: sh @@ -126,7 +128,7 @@ with nginx ^^^^^^^^^^ If nginx is not installed (uwsgi will not work with the package -nginx-light) : +nginx-light): .. code:: sh @@ -136,7 +138,7 @@ Hosted at / """"""""""" Create the configuration file /etc/nginx/sites-available/searx with this -content : +content: .. code:: nginx @@ -151,7 +153,7 @@ content : } } -Restart service : +Restart service: .. code:: sh @@ -159,10 +161,10 @@ Restart service : sudo service uwsgi restart from subdirectory URL (/searx) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""""""""""" Add this configuration in the server config file -/etc/nginx/sites-available/default : +/etc/nginx/sites-available/default: .. code:: nginx @@ -183,7 +185,7 @@ Enable base\_url in searx/settings.yml base_url : http://your.domain.tld/searx/ -Restart service : +Restart service: .. code:: sh @@ -195,7 +197,7 @@ disable logs for better privacy you can disable nginx logs about searx. -how to proceed : below ``uwsgi_pass`` in +how to proceed: below ``uwsgi_pass`` in /etc/nginx/sites-available/default add :: @@ -203,23 +205,23 @@ how to proceed : below ``uwsgi_pass`` in access_log /dev/null; error_log /dev/null; -Restart service : +Restart service: .. code:: sh sudo service nginx restart with apache ------------ +^^^^^^^^^^^ -Add wsgi mod : +Add wsgi mod: .. code:: sh sudo apt-get install libapache2-mod-uwsgi sudo a2enmod uwsgi -Add this configuration in the file /etc/apache2/apache2.conf : +Add this configuration in the file /etc/apache2/apache2.conf: .. code:: apache @@ -233,29 +235,29 @@ Note that if your instance of searx is not at the root, you should change ```` by the location of your instance, like ````. -Restart Apache : +Restart Apache: .. code:: sh sudo /etc/init.d/apache2 restart disable logs ------------- +"""""""""""" For better privacy you can disable Apache logs. -WARNING : not tested +WARNING: not tested -WARNING : you can only disable logs for the whole (virtual) server not +WARNING: you can only disable logs for the whole (virtual) server not for a specific path. -Go back to /etc/apache2/apache2.conf and above ```` add : +Go back to /etc/apache2/apache2.conf and above ```` add: .. code:: apache CustomLog /dev/null combined -Restart Apache : +Restart Apache: .. code:: sh @@ -272,6 +274,27 @@ How to update git stash git pull origin master git stash apply - pip install --upgrade -r requirements.txt + ./manage.sh update_packages sudo service uwsgi restart +Docker +------ + +Make sure you have installed Docker. For instance, you can deploy searx like this: + +.. code:: sh + + docker pull wonderfall/searx + docker run -d --name searx -p $PORT:8888 wonderfall/searx + +Go to http://localhost:$PORT. + +See https://hub.docker.com/r/wonderfall/searx/ for more informations. + +It's also possible to build searx from the embedded Dockerfile. + +.. code:: sh + + git clone https://github.com/asciimoo/searx.git + cd searx + docker build -t whatever/searx . -- cgit v1.2.3 From fb62d01194bc6049a0dc1e5ffbc3ca2f9536f26c Mon Sep 17 00:00:00 2001 From: Thomas Pointhuber Date: Thu, 21 Jan 2016 16:25:40 +0100 Subject: [enh] improve translation documentation --- docs/dev/translation.rst | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst index 0fc02a7de..c070c36ea 100644 --- a/docs/dev/translation.rst +++ b/docs/dev/translation.rst @@ -6,23 +6,29 @@ run these commands in the root directory of searx Add new language ~~~~~~~~~~~~~~~~ -``pybabel init -i messages.pot -d searx/translations -l it`` +.. code:: shell + + pybabel init -i messages.pot -d searx/translations -l it Update .po files ~~~~~~~~~~~~~~~~ -``./utils/update-translations.sh`` +.. code:: shell + + ./utils/update-translations.sh You may have errors here. In that case, edit the ``update-translations.sh`` script to change ``pybabel`` to -``pybabel-python2`` +``pybabel-python2 or pybabel2`` After this step, you can modify the .po files. Compile translations ~~~~~~~~~~~~~~~~~~~~ -``pybabel compile -d searx/translations`` +.. code:: shell + + pybabel compile -d searx/translations Transifex stuff ~~~~~~~~~~~~~~~ @@ -32,12 +38,14 @@ Init Project .. code:: shell + tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/ + tx set --auto-local -r searx.messagespo 'searx/translations//LC_MESSAGES/messages.po' \ --source-lang en --type PO --source-file messages.pot --execute -http://docs.transifex.com/developer/client/set +http://docs.transifex.com/client/init/ -*TODO: mapping between transifex and searx* +http://docs.transifex.com/client/set/ Get translations ^^^^^^^^^^^^^^^^ @@ -46,29 +54,27 @@ Get translations tx pull -a -http://docs.transifex.com/developer/client/pull +http://docs.transifex.com/client/pull Upload source File ^^^^^^^^^^^^^^^^^^ -:: +.. code:: shell tx push -s Upload all Translation ^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code:: shell tx push -s -t -upload specifc Translation (only for admins) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +upload specifc Translation +~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +.. code:: shell tx push -t -l tr -http://docs.transifex.com/developer/client/push - -*TODO: upload empty files? (new translations)* +http://docs.transifex.com/client/push -- cgit v1.2.3 From cf9bd14a7d8a34c08af5f7a6370525c559d2ed96 Mon Sep 17 00:00:00 2001 From: Thomas Pointhuber Date: Thu, 21 Jan 2016 16:30:42 +0100 Subject: [fix] little typo --- docs/dev/translation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst index c070c36ea..bc32eda90 100644 --- a/docs/dev/translation.rst +++ b/docs/dev/translation.rst @@ -19,7 +19,7 @@ Update .po files You may have errors here. In that case, edit the ``update-translations.sh`` script to change ``pybabel`` to -``pybabel-python2 or pybabel2`` +``pybabel-python2`` or ``pybabel2`` After this step, you can modify the .po files. -- cgit v1.2.3 From 016ab5c1e87fa86b5e618616e1dd9d49d880c506 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Mon, 1 Feb 2016 21:28:13 +0100 Subject: add development quickstart --- docs/dev/quickstart.rst | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 91 insertions(+) create mode 100644 docs/dev/quickstart.rst (limited to 'docs') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst new file mode 100644 index 000000000..edca8af5e --- /dev/null +++ b/docs/dev/quickstart.rst @@ -0,0 +1,90 @@ +Development Quickstart +---------------------- + +This quickstart guide gets your environment set up with searx. Furthermore, it gives a +short introduction to the new manage.sh script. + +How to setup your development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, clone the source code of searx to the desired folder. In this case the source +is cloned to ~/myprojects/searx. Then create and activate the searx-ve +virtualenv and install the required packages using manage.sh. + +.. code:: sh + + cd ~/myprojects + git clone https://github.com/asciimoo/searx.git + cd searx + virtualenv searx-ve + . ./searx-ve/bin/activate + ./manage.sh update_dev_packages + + +How to run tests +~~~~~~~~~~~~~~~~ + +Tests can be run using the manage.sh script. + +Following tests and checks are available: + +- Unit tests + +- Selenium tests + +- PEP8 validation + +- Unit test coverage check + +For example unit tests are run with the command below: + +.. code:: sh + + ./manage.sh unit_tests + +For further test options, please consult the help of the manage.sh script. + + +How to compile styles and javascript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How to build styles +^^^^^^^^^^^^^^^^^^^ + +Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt. + +.. code:: sh + + sudo apt-get install nodejs + sudo npm install -g less + + +OR + +.. code:: sh + + sudo apt-get install node-less + +After satisfying the requirements styles can be build using manage.sh + +.. code:: sh + + ./manage.sh styles + + +How to build the source of the oscar theme +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first +Node has to be installed. + +.. code:: sh + + sudo apt-get install nodejs + sudo npm install -g grunt-cli + +After installing grunt, the files can be built using the following command: + +.. code:: sh + + ./manage.sh build_grunt diff --git a/docs/index.rst b/docs/index.rst index 09dd1798d..d6e21894b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,7 @@ Developer documentation .. toctree:: :maxdepth: 1 + dev/quickstart dev/contribution_guide dev/install/installation dev/engine_overview -- cgit v1.2.3 From 9c56154cfe121c6b89f48dd6b9af4e5e029d8a6e Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 21 Apr 2016 13:15:04 +0200 Subject: add dev tips to quickstart --- docs/dev/contribution_guide.rst | 2 ++ docs/dev/quickstart.rst | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 73f4ea332..65e587294 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -64,6 +64,8 @@ In order to submit a patch, please follow the steps below: - Create a pull request. +For more help on getting started with searx development, see :ref:`devquickstart`. + Translation ~~~~~~~~~~~ diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index edca8af5e..92ef62385 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -1,3 +1,5 @@ +.. _devquickstart: + Development Quickstart ---------------------- @@ -88,3 +90,19 @@ After installing grunt, the files can be built using the following command: .. code:: sh ./manage.sh build_grunt + + + +Tips for debugging/development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Turn on debug logging + Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea + to turn on debug logging. When debug logging is enabled a stack trace appears, + instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting + ``debug: False`` to ``debug: True`` in settings.yml. + +2. Run ``./manage.sh tests`` before creating a PR. + Failing build on Travis is common because of PEP8 checks. So a new commit must be created + containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run + locally before creating a PR. -- cgit v1.2.3 From 2430baa1fd6e4ecba4bc72a8e71c49a38b424216 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 21 Apr 2016 13:16:18 +0200 Subject: update install docs on reverse proxy --- docs/dev/install/installation.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index e15ff8b25..d69f30e8f 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -171,6 +171,8 @@ Add this configuration in the server config file location = /searx { rewrite ^ /searx/; } location /searx { try_files $uri @searx; + proxy_pass http://localhost:9999/; + proxy_set_header X-Script-Name /searx; } location @searx { uwsgi_param SCRIPT_NAME /searx; @@ -179,6 +181,7 @@ Add this configuration in the server config file uwsgi_pass unix:/run/uwsgi/app/searx/socket; } + Enable base\_url in searx/settings.yml :: -- cgit v1.2.3 From b40d7a2b36014f8db825c06350ed84db7eed67d5 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 21 Apr 2016 14:30:17 +0200 Subject: add reverse proxy configuration --- docs/dev/install/installation.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index d69f30e8f..cbbd25f57 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -171,8 +171,6 @@ Add this configuration in the server config file location = /searx { rewrite ^ /searx/; } location /searx { try_files $uri @searx; - proxy_pass http://localhost:9999/; - proxy_set_header X-Script-Name /searx; } location @searx { uwsgi_param SCRIPT_NAME /searx; @@ -182,6 +180,23 @@ Add this configuration in the server config file } +OR + +using reverse proxy +(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.) + +.. code:: nginx + + location /searx { + proxy_pass http://127.0.0.1:8888; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Scheme $scheme; + proxy_set_header X-Script-Name /searx; + proxy_buffering off; + } + + Enable base\_url in searx/settings.yml :: -- cgit v1.2.3 From ffcceed5170209bbc2fe54322973d72c9c4fff78 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Sat, 9 Jul 2016 21:46:20 +0200 Subject: version bump to 0.9.0 && year to 2016 --- docs/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 30fe90313..b1392bab1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,7 +49,7 @@ master_doc = 'index' # General information about the project. project = u'searx' -copyright = u'2015, Adam Tauber' +copyright = u'2015-2016, Adam Tauber' author = u'Adam Tauber' # The version info for the project you're documenting, acts as replacement for @@ -57,9 +57,9 @@ author = u'Adam Tauber' # built documents. # # The short X.Y version. -version = '0.8.0' +version = '0.9.0' # The full version, including alpha/beta/rc tags. -release = '0.8.0' +release = '0.9.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- 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/admin/api.rst | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/dev/plugins.rst | 34 ++++++++++----------- docs/dev/search_api.rst | 19 ++++++++---- docs/index.rst | 21 +++++++++---- 4 files changed, 123 insertions(+), 29 deletions(-) create mode 100644 docs/admin/api.rst (limited to 'docs') diff --git a/docs/admin/api.rst b/docs/admin/api.rst new file mode 100644 index 000000000..94508a28c --- /dev/null +++ b/docs/admin/api.rst @@ -0,0 +1,78 @@ +.. _adminapi: + +Administration API +------------------ + +Get configuration data +~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + GET /config + +Sample response +``````````````` + +.. code:: sh + + { + "autocomplete": "", + "categories": [ + "map", + "it", + "images", + ], + "default_locale": "", + "default_theme": "oscar", + "engines": [ + { + "categories": [ + "map" + ], + "enabled": true, + "name": "openstreetmap", + "shortcut": "osm" + }, + { + "categories": [ + "it" + ], + "enabled": true, + "name": "arch linux wiki", + "shortcut": "al" + }, + { + "categories": [ + "images" + ], + "enabled": true, + "name": "google images", + "shortcut": "goi" + }, + { + "categories": [ + "it" + ], + "enabled": false, + "name": "bitbucket", + "shortcut": "bb" + }, + ], + "instance_name": "searx", + "locales": { + "de": "Deutsch (German)", + "en": "English", + "eo": "Esperanto (Esperanto)", + }, + "plugins": [ + { + "enabled": true, + "name": "HTTPS rewrite" + }, + { + "enabled": false, + "name": "Vim-like hotkeys" + } + ], + "safe_search": 0 + } diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst index c51fdf0eb..0f52af0d8 100644 --- a/docs/dev/plugins.rst +++ b/docs/dev/plugins.rst @@ -1,11 +1,11 @@ Plugins ------- -Plugins can extend/replace functionality of various components inside +Plugins can extend or replace functionality of various components of searx. -example\_plugin.py -~~~~~~~~~~~~~~~~~~ +Example plugin +~~~~~~~~~~~~~~ .. code:: python @@ -24,22 +24,22 @@ example\_plugin.py ctx['search'].suggestions.add('example') return True -Currently implemented plugin entry points (a.k.a hooks) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Plugin entry points +~~~~~~~~~~~~~~~~~~~ -- Pre search hook (``pre_search``) -- Post search hook (``post_search``) -- Result hook (``on_result``) (is called if a new result is added (see - https\_rewrite plugin)) +Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin. -Feel free to add more hooks to the code if it is required by a plugin. +Pre search hook +``````````````` -TODO -~~~~ +Runs BEFORE the search request. Function to implement: ``pre_search`` -- Better documentation -- More hooks -- search hook (is called while searx is requesting results (for - example: things like math-solver), the different hooks are running - parallel) +Post search hook +```````````````` +Runs AFTER the search request. Function to implement: ``post_search`` + +Result hook +``````````` + +Runs when a new result is added to the result list. Function to implement: ``on_result`` 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. diff --git a/docs/index.rst b/docs/index.rst index d6e21894b..c24eff4d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ -Privacy-respecting free metasearch engine -========================================= +Welcome to searx +================ -Searx is a free software internet metasearch engine which aggregates results from other search engines, while not storing information about its users. Searx does not track or profile its users, nor does it share its users' data with third parties. Additionally, searx can be used over Tor for online anonymity. +Searx is a free software internet metasearch engine which aggregates results from more than 70 engines, while not storing information about its users. Searx does not track or profile its users, nor does it share its users' data with third parties. Additionally, searx can be used over Tor for online anonymity. Features @@ -15,16 +15,26 @@ Features - Does not collect its users data - Offers secure, encrypted connections (HTTPS/SSL) - Hosted by organisations, such as La Quadrature du Net, which promote digital rights + - About 70 supported search engines + - Easy intergration with any search engine -Further reading ---------------- +User documentation +------------------ .. toctree:: :maxdepth: 1 user/search_syntax +Administrator documentation +--------------------------- + +.. toctree:: + :maxdepth: 1 + + dev/install/installation + admin/api Developer documentation ----------------------- @@ -34,7 +44,6 @@ Developer documentation dev/quickstart dev/contribution_guide - dev/install/installation dev/engine_overview dev/search_api dev/plugins -- cgit v1.2.3 From 521f398709ea481fdf55f1e4c111f063f91fa8c0 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Sat, 9 Jul 2016 23:01:00 +0200 Subject: disable breaking "searx" into multiple lines --- docs/_themes/searx_theme/static/style.css_t | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/_themes/searx_theme/static/style.css_t b/docs/_themes/searx_theme/static/style.css_t index 4a266671f..0a312b76e 100644 --- a/docs/_themes/searx_theme/static/style.css_t +++ b/docs/_themes/searx_theme/static/style.css_t @@ -38,6 +38,8 @@ div.bodywrapper { div.sphinxsidebar { width: {{ sidebar_width }}; + word-wrap: normal !important; + overflow-wrap: normal !important; } hr { -- cgit v1.2.3 From 9e135f9fab3894cc86264cb7552252ef0cf10581 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Fri, 15 Jul 2016 18:41:05 +0200 Subject: simplify index page --- docs/dev/install/installation.rst | 2 ++ docs/index.rst | 21 ++++++++++++--------- 2 files changed, 14 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index cbbd25f57..b641a628e 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -1,3 +1,5 @@ +.. _installation: + Installation ============ diff --git a/docs/index.rst b/docs/index.rst index c24eff4d2..46960c0fc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,25 @@ Welcome to searx ================ -Searx is a free software internet metasearch engine which aggregates results from more than 70 engines, while not storing information about its users. Searx does not track or profile its users, nor does it share its users' data with third parties. Additionally, searx can be used over Tor for online anonymity. +Search without being tracked. +Searx is a free internet metasearch engine which aggregates results from more than 70 search services. Users are neither tracked nor profiled. Additionally, searx can be used over Tor for online anonymity. + +Get started with searx by using one of the `public instances`_. If you don't trust anyone, you can set up your own, see :ref:`installation`. + +.. _public instances: https://github.com/asciimoo/searx/wiki/Searx-instances Features -------- - Self hosted - - Does not track its users - - Does not share its users data with third parties - - Does not use cookies by default - - Does not profile its users - - Does not collect its users data - - Offers secure, encrypted connections (HTTPS/SSL) - - Hosted by organisations, such as La Quadrature du Net, which promote digital rights + - No user tracking + - No user profiling - About 70 supported search engines - - Easy intergration with any search engine + - Easy intergration with any search engines + - Cookies are not used by default + - Secure, encrypted connections (HTTPS/SSL) + - Hosted by organisations, such as La Quadrature du Net, which promote digital rights User documentation -- 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') 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 013139b036e31043e25991112a34588011650243 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Tue, 6 Sep 2016 18:16:29 +0200 Subject: add embedded search to docs --- docs/admin/api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs') diff --git a/docs/admin/api.rst b/docs/admin/api.rst index 94508a28c..8d6162247 100644 --- a/docs/admin/api.rst +++ b/docs/admin/api.rst @@ -76,3 +76,19 @@ Sample response ], "safe_search": 0 } + +Embed search bar +---------------- + +The search bar can be embedded into websites. Just paste the example into the HTML of the site. +URL of the searx instance and values are customizable. + +.. code:: html + +
+ + + + + +
-- 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') 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 dca4d276a45cc85f97db326636b4b671a3263225 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sun, 30 Oct 2016 01:01:22 +0200 Subject: add sample config of filtron --- docs/admin/filtron.rst | 114 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 115 insertions(+) create mode 100644 docs/admin/filtron.rst (limited to 'docs') diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst new file mode 100644 index 000000000..c422cb0a8 --- /dev/null +++ b/docs/admin/filtron.rst @@ -0,0 +1,114 @@ +How to protect an instance +========================== + +Searx depens on external search services. To avoid the abuse of these services it is advised to limit the number of requests processed by searx. + +An application firewall, ``filtron`` solves exactly this problem. Information on how to install it can be found at the `project page of filtron `__. + +Sample configuration of filtron +------------------------------- + +An example configuration can be find below. This configuration limits the access of + + * scripts or applications (roboagent limit) + + * webcrawlers (botlimit) + + * IPs which send too many requests (IP limit) + + * too many json, csv, etc. requests (rss/json limit) + + * the same UserAgent of if too many requests (useragent limit) + + +.. code:: json + + [ + { + "name": "search request", + "filters": ["Param:q", "Path=^(/|/search)$"], + "interval": , + "limit": , + "subrules": [ + { + "name": "roboagent limit", + "interval": , + "limit": , + "filters": ["Header:User-Agent=(curl|cURL|Wget|python-requests|Scrapy|FeedFetcher|Go-http-client)"], + "actions": [ + {"name": "block", + "params": {"message": "Rate limit exceeded"}} + ] + }, + { + "name": "botlimit", + "limit": 0, + "stop": true, + "filters": ["Header:User-Agent=(Googlebot|bingbot|Baiduspider|yacybot|YandexMobileBot|YandexBot|Yahoo! Slurp|MJ12bot|AhrefsBot|archive.org_bot|msnbot|MJ12bot|SeznamBot|linkdexbot|Netvibes|SMTBot|zgrab|James BOT)"], + "actions": [ + {"name": "block", + "params": {"message": "Rate limit exceeded"}} + ] + }, + { + "name": "IP limit", + "interval": , + "limit": , + "stop": true, + "aggregations": ["Header:X-Forwarded-For"], + "actions": [ + {"name": "block", + "params": {"message": "Rate limit exceeded"}} + ] + }, + { + "name": "rss/json limit", + "interval": , + "limit": , + "stop": true, + "filters": ["Param:format=(csv|json|rss)"], + "actions": [ + {"name": "block", + "params": {"message": "Rate limit exceeded"}} + ] + }, + { + "name": "useragent limit", + "interval": , + "limit": , + "aggregations": ["Header:User-Agent"], + "actions": [ + {"name": "block", + "params": {"message": "Rate limit exceeded"}} + ] + } + ] + } + ] + + + +Route request through filtron +----------------------------- + +Filtron can be started using the following command: + +.. code:: bash + + $ filtron -rules rules.json + +It listens on 127.0.0.1:4004 and forwards filtered requests to 127.0.0.1:8888 by default. + +Use it along with ``nginx`` with the following example configuration. + +.. code:: bash + + location / { + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Scheme $scheme; + proxy_pass http://127.0.0.1:4004/; + } + +Requests are coming from port 4004 going through filtron and then forwarded to port 8888 where a searx is being run. diff --git a/docs/index.rst b/docs/index.rst index 46960c0fc..18e4b6d07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,7 @@ Administrator documentation dev/install/installation admin/api + admin/filtron Developer documentation ----------------------- -- cgit v1.2.3 From c2cf46092e7e805587fde191ea9c620ee2bcb158 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Fri, 4 Nov 2016 18:38:07 +0100 Subject: docs: fix typos based on #653 --- docs/dev/engine_overview.rst | 226 ++++++++++++++++++++++--------------------- docs/dev/plugins.rst | 2 +- docs/index.rst | 2 +- 3 files changed, 116 insertions(+), 114 deletions(-) (limited to 'docs') diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 186cc0f94..da7ee2710 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -30,15 +30,17 @@ settings. However, the standard way is the following: engine file ~~~~~~~~~~~ -+---------------------+-----------+-----------------------------------------+ -| argument | type | information | -+=====================+===========+=========================================+ -| categories | list | pages, in which the engine is working | -+---------------------+-----------+-----------------------------------------+ -| paging | boolean | support multible pages | -+---------------------+-----------+-----------------------------------------+ -| language\_support | boolean | support language choosing | -+---------------------+-----------+-----------------------------------------+ ++----------------------+-----------+-----------------------------------------+ +| argument | type | information | ++======================+===========+=========================================+ +| categories | list | pages, in which the engine is working | ++----------------------+-----------+-----------------------------------------+ +| paging | boolean | support multible pages | ++----------------------+-----------+-----------------------------------------+ +| language\_support | boolean | support language choosing | ++----------------------+-----------+-----------------------------------------+ +| time\_range\_support | boolean | support search time range | ++----------------------+-----------+-----------------------------------------+ settings.yml ~~~~~~~~~~~~ @@ -186,126 +188,126 @@ To set another media-type as default, the parameter default ~~~~~~~ -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+====================================================================================================================================+ -| url | string, which is representing the url of the result | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| content | string, which is giving a general result-text | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, represent when the result is published | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+---------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+===============================================================================================================+ +| url | string, url of the result | ++--------------------+---------------------------------------------------------------------------------------------------------------+ +| title | string, title of the result | ++--------------------+---------------------------------------------------------------------------------------------------------------+ +| content | string, general result-text | ++--------------------+---------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, time of publish | ++--------------------+---------------------------------------------------------------------------------------------------------------+ images ~~~~~~ to use this template, the parameter -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+===========================================================================================================================================================+ -| template | is set to ``images.html`` | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, which is representing the url to the result site | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result *(partly implemented)* | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| content | *(partly implemented)* | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, represent when the result is published *(partly implemented)* | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| img\_src | string, which is representing the url to the result image | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| thumbnail\_src | string, which is representing the url to a small-preview image | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+=======================================================================================================================================+ +| template | is set to ``images.html`` | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, url to the result site | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, title of the result *(partly implemented)* | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| content | *(partly implemented)* | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, time of publish *(partly implemented)* | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| img\_src | string, url to the result image | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| thumbnail\_src | string, url to a small-preview image | ++--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ videos ~~~~~~ -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+====================================================================================================================================+ -| template | is set to ``videos.html`` | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, which is representing the url of the result | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| content | *(not implemented yet)* | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, represent when the result is published | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| thumbnail | string, which is representing the url to a small-preview image | -+--------------------+------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++====================+==============================================================================================================+ +| template | is set to ``videos.html`` | ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| url | string, url of the result | ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| title | string, title of the result | ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| content | *(not implemented yet)* | ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, time of publish | ++--------------------+--------------------------------------------------------------------------------------------------------------+ +| thumbnail | string, url to a small-preview image | ++--------------------+--------------------------------------------------------------------------------------------------------------+ torrent ~~~~~~~ -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| template | is set to ```torrent.html``` | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, which is representing the url of the result | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| content | string, which is giving a general result-text | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, represent when the result is published *(not implemented yet)* | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| seed | int, number of seeder | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| leech | int, number of leecher | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| filesize | int, size of file in bytes | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| files | int, number of files | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| magnetlink | string, which is the `magnetlink `__ of the result | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ -| torrentfile | string, which is the torrentfile of the result | -+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| template | is set to ``torrent.html`` | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| url | string, url of the result | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| title | string, title of the result | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| content | string, general result-text | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, time of publish *(not implemented yet)* | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| seed | int, number of seeder | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| leech | int, number of leecher | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| filesize | int, size of file in bytes | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| files | int, number of files | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| magnetlink | string, `magnetlink `__ of the result | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| torrentfile | string, torrentfile of the result | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------+ map ~~~ -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+=========================+====================================================================================================================================+ -| url | string, which is representing the url of the result | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, which is representing the title of the result | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| content | string, which is giving a general result-text | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, represent when the result is published | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| latitude | latitude of result (in decimal format) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| longitude | longitude of result (in decimal format) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| boundingbox | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| geojson | geojson of result (http://geojson.org) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| osm.type | type of osm-object (if OSM-Result) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| osm.id | id of osm-object (if OSM-Result) | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.name | name of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.road | street adress of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.house\_number | house number of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.locality | city, place of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.postcode | postcode of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ -| address.country | country of object | -+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+ ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| result-parameter | information | ++=========================+==============================================================================================================+ +| url | string, url of the result | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| title | string, title of the result | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| content | string, general result-text | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| publishedDate | `datetime.datetime `__, time of publish | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| latitude | latitude of result (in decimal format) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| longitude | longitude of result (in decimal format) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| boundingbox | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| geojson | geojson of result (http://geojson.org) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| osm.type | type of osm-object (if OSM-Result) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| osm.id | id of osm-object (if OSM-Result) | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.name | name of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.road | street name of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.house\_number | house number of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.locality | city, place of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.postcode | postcode of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ +| address.country | country of object | ++-------------------------+--------------------------------------------------------------------------------------------------------------+ diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst index 0f52af0d8..1d77f8611 100644 --- a/docs/dev/plugins.rst +++ b/docs/dev/plugins.rst @@ -11,7 +11,7 @@ Example plugin name = 'Example plugin' description = 'This plugin extends the suggestions with the word "example"' - default_on = False # disable by default + default_on = False # disabled by default js_dependencies = tuple() # optional, list of static js files css_dependencies = tuple() # optional, list of static css files diff --git a/docs/index.rst b/docs/index.rst index 18e4b6d07..81b9fe33e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ Features - No user tracking - No user profiling - About 70 supported search engines - - Easy intergration with any search engines + - Easy integration with any search engine - Cookies are not used by default - Secure, encrypted connections (HTTPS/SSL) - Hosted by organisations, such as La Quadrature du Net, which promote digital rights -- cgit v1.2.3 From ee18ad780ea5c069c98e33f395dcd972c8a0bd09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Fri, 4 Nov 2016 21:53:11 +0100 Subject: conf: bump searx version to 0.10.0 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index b1392bab1..3ede34457 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,9 +57,9 @@ author = u'Adam Tauber' # built documents. # # The short X.Y version. -version = '0.9.0' +version = '0.10.0' # The full version, including alpha/beta/rc tags. -release = '0.9.0' +release = '0.10.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 31ea4280bfab409a2518f95af26da0de32f4645e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 5 Nov 2016 11:48:49 +0100 Subject: "why use a personal instance?" page --- docs/index.rst | 1 + docs/user/own-instance.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/user/own-instance.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 81b9fe33e..da5a886d0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ User documentation :maxdepth: 1 user/search_syntax + admin/own-instance Administrator documentation --------------------------- diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst new file mode 100644 index 000000000..56f9b0111 --- /dev/null +++ b/docs/user/own-instance.rst @@ -0,0 +1,43 @@ +Why use a private instance? +=========================== + +"Is it worth to run my own instance?" is a common question among searx users. Before answering this question, see what options a searx 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 searx 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 searx protects its users. + +How does searx protect privacy? +------------------------------- + +Searx 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 forwarding IP addresses, 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. + +Searx does not serve adds 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, he/she has to trust the administrator of that instance. +This means that the user of the public instance does not know whether his/her 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 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 searx 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 searx are available to users no matter what kind of instance they use. + +If someone is on the go or just wants to try searx 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 f55eea083f9100e4275208c34347088be251c83f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 5 Nov 2016 11:49:07 +0100 Subject: generated files of parent --- docs/index.rst | 2 +- docs/user/own-instance.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index da5a886d0..abd57f08c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,7 +29,7 @@ User documentation :maxdepth: 1 user/search_syntax - admin/own-instance + user/own-instance Administrator documentation --------------------------- diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst index 56f9b0111..3f2802282 100644 --- a/docs/user/own-instance.rst +++ b/docs/user/own-instance.rst @@ -16,7 +16,7 @@ Searx protects the privacy of its users in multiple ways regardless of the type 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 forwarding IP addresses, 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. +Removing private data means not forwarding 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 insance. But searx can be ocnfigured to use proxy or Tor. `Result proxy `__ is supported, too. Searx does not serve adds 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. -- cgit v1.2.3 From 50f25193c17707157c905f455b1d3a27c3edc001 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 5 Nov 2016 16:22:29 +0100 Subject: engine overview fix torrent table --- docs/dev/engine_overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index da7ee2710..d57ca5b38 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -247,7 +247,7 @@ torrent +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | result-parameter | information | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ ++==================+=======================================================================================================================================+ | template | is set to ``torrent.html`` | +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | url | string, url of the result | -- cgit v1.2.3 From d0d2d18a4d1d47b5809c9129f2b891ab6f80e42b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 5 Nov 2016 16:26:53 +0100 Subject: fix typos in own instance page --- docs/user/own-instance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst index 3f2802282..71d9f11af 100644 --- a/docs/user/own-instance.rst +++ b/docs/user/own-instance.rst @@ -16,7 +16,7 @@ Searx protects the privacy of its users in multiple ways regardless of the type 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 forwarding 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 insance. But searx can be ocnfigured to use proxy or Tor. `Result proxy `__ is supported, too. +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 searx can be configured to use proxy or Tor. `Result proxy `__ is supported, too. Searx does not serve adds 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. -- cgit v1.2.3 From 6ecd8e3bd72df43d903800ee05e33185efe22ee6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sun, 20 Nov 2016 21:12:52 +0100 Subject: installation: nginx mod to sites-enabled --- docs/dev/install/installation.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index b641a628e..b02718fe3 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -3,20 +3,13 @@ Installation ============ -Step by step installation for Debian/Ubuntu with virtualenv. - -Source: https://about.okhin.fr/posts/Searx/ with some additions - -How to: `Setup searx in a couple of hours with a free SSL -certificate `__ - .. contents:: :depth: 3 Basic installation ------------------ -For Ubuntu, be sure to have enable universe repository. +Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure to have enable universe repository. Install packages: @@ -166,7 +159,7 @@ from subdirectory URL (/searx) """""""""""""""""""""""""""""" Add this configuration in the server config file -/etc/nginx/sites-available/default: +/etc/nginx/sites-enabled/default: .. code:: nginx @@ -318,3 +311,11 @@ It's also possible to build searx from the embedded Dockerfile. git clone https://github.com/asciimoo/searx.git cd searx docker build -t whatever/searx . + +References +========== + + * https://about.okhin.fr/posts/Searx/ with some additions + + * How to: `Setup searx in a couple of hours with a free SSL certificate `__ + -- cgit v1.2.3 From e43e5af207580bab7aeb3b8d866a27b282babab7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 18 Mar 2017 23:55:20 +0100 Subject: bump searx version to 0.11.0 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 3ede34457..012499570 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,9 +57,9 @@ author = u'Adam Tauber' # built documents. # # The short X.Y version. -version = '0.10.0' +version = '0.11.0' # The full version, including alpha/beta/rc tags. -release = '0.10.0' +release = '0.11.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From 1bd51c6de2f31ad15e5689ee7ff80f2283baa817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Sat, 18 Mar 2017 23:57:19 +0100 Subject: rewrite Translation page --- docs/dev/translation.rst | 69 ++++++++++++++++++------------------------------ 1 file changed, 25 insertions(+), 44 deletions(-) (limited to 'docs') diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst index bc32eda90..ab4dd98cb 100644 --- a/docs/dev/translation.rst +++ b/docs/dev/translation.rst @@ -1,80 +1,61 @@ Translation =========== -run these commands in the root directory of searx +Requirements +------------ -Add new language -~~~~~~~~~~~~~~~~ + * Transifex account -.. code:: shell + * Installed CLI tool of Transifex - pybabel init -i messages.pot -d searx/translations -l it +Init Transifex project +---------------------- -Update .po files -~~~~~~~~~~~~~~~~ +After installing ``transifex`` using pip, run the following command to initialize the project. .. code:: shell - ./utils/update-translations.sh + tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/ -You may have errors here. In that case, edit the -``update-translations.sh`` script to change ``pybabel`` to -``pybabel-python2`` or ``pybabel2`` -After this step, you can modify the .po files. +After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it into the configuration file. -Compile translations -~~~~~~~~~~~~~~~~~~~~ +Create a configuration file for ``tx`` named ``$HOME/.tx/config``. .. code:: shell - pybabel compile -d searx/translations + [main] + host = https://www.transifex.com + [searx.messagespo] + file_filter = searx/translations//LC_MESSAGES/messages.po + source_file = messages.pot + source_lang = en + type = PO -Transifex stuff -~~~~~~~~~~~~~~~ -Init Project -^^^^^^^^^^^^ +Then run ``tx set``: .. code:: shell - tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/ - tx set --auto-local -r searx.messagespo 'searx/translations//LC_MESSAGES/messages.po' \ --source-lang en --type PO --source-file messages.pot --execute -http://docs.transifex.com/client/init/ -http://docs.transifex.com/client/set/ +Update translations +------------------- -Get translations -^^^^^^^^^^^^^^^^ +To retrieve the latest translations, pull it from Transifex. .. code:: shell tx pull -a -http://docs.transifex.com/client/pull - -Upload source File -^^^^^^^^^^^^^^^^^^ - -.. code:: shell - - tx push -s - -Upload all Translation -^^^^^^^^^^^^^^^^^^^^^^ +Then check the new languages. If strings translated are not enough, delete those folders, because +those should not be compiled. Call the command below to compile the ``.po`` files. .. code:: shell - tx push -s -t - -upload specifc Translation -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code:: shell + pybabel compile -d searx/translations - tx push -t -l tr -http://docs.transifex.com/client/push +After the compilation is finished commit the ``.po`` and ``.mo`` files and create a PR. -- cgit v1.2.3 From b8f5c75374a491d883036a9532bb98d02284c8a9 Mon Sep 17 00:00:00 2001 From: James Coleman Date: Wed, 19 Apr 2017 15:29:32 -0500 Subject: Corrected spelling of ads in user/own-instance.html --- docs/user/own-instance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst index 71d9f11af..555f82cca 100644 --- a/docs/user/own-instance.rst +++ b/docs/user/own-instance.rst @@ -18,7 +18,7 @@ Searx protects the privacy of its users in multiple ways regardless of the type 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 searx can be configured to use proxy or Tor. `Result proxy `__ is supported, too. -Searx does not serve adds 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. +Searx 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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3 From 93e6258463d67a33c956788a5552627a9798fb5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Fri, 12 May 2017 22:51:48 +0200 Subject: add first blog entry on python3 support --- docs/_themes/searx_theme/relations.html | 1 + docs/blog/blog.rst | 7 +++++ docs/blog/python3.rst | 54 ++++++++++++++++++++++++++++++++ docs/blog/searxpy3.png | Bin 0 -> 30947 bytes 4 files changed, 62 insertions(+) create mode 100644 docs/blog/blog.rst create mode 100644 docs/blog/python3.rst create mode 100644 docs/blog/searxpy3.png (limited to 'docs') diff --git a/docs/_themes/searx_theme/relations.html b/docs/_themes/searx_theme/relations.html index 13cfa019d..b7539e5a1 100644 --- a/docs/_themes/searx_theme/relations.html +++ b/docs/_themes/searx_theme/relations.html @@ -3,6 +3,7 @@ diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst new file mode 100644 index 000000000..aad448c6b --- /dev/null +++ b/docs/blog/blog.rst @@ -0,0 +1,7 @@ +Blog +==== + +.. toctree:: + :maxdepth: 1 + + python3 diff --git a/docs/blog/python3.rst b/docs/blog/python3.rst new file mode 100644 index 000000000..f9a058902 --- /dev/null +++ b/docs/blog/python3.rst @@ -0,0 +1,54 @@ +Introducing Python3 support +=========================== + +As most operation systems are coming with Python3 installed by default. So it is time for searx to support Python3. But don't worry support of Python2.7 won't be dropped. + +.. image:: hurray.png + :scale: 50 % + :alt: hurray + :align: center + + +How to run searx using Python3 +------------------------------ + +Please make sure that you run at least Python3.5. + +To run searx, first a Python3 virtualenv should be created. After entering the virtualenv, +dependencies must be installed. Then run searx with python3 instead of the usual python command. + +.. code:: sh + + virtualenv -p python3 venv3 + source venv3/bin/activate + pip3 install -r requirements.txt + python3 searx/webapp.py + + +If you want to run searx using Python2.7, you don't have to do anything differently as before. + +Fun facts +--------- + +- 115 files were changed when implementing the support for both Python versions. + +- All of the dependencies was compatible except for the robotframework used for browser tests. Thus, these tests were migrated to splinter. So from now on both versions are being tested on Travis and can be tested locally. + +If you found bugs... +-------------------- + +...please open an issue on `GitHub`_. Make sure that you mention your Python version in your issue, +so we can investigate it properly. + +.. _GitHub: https://github.com/asciimoo/searx/issues + +Acknowledgement +--------------- + +This development was sponsored by `NLnet Foundation`_. + +.. _NLnet Foundation: https://nlnet.nl/ + + +| Happy hacking. +| kvch // 2017.05.13 22:57 diff --git a/docs/blog/searxpy3.png b/docs/blog/searxpy3.png new file mode 100644 index 000000000..8eeaeec55 Binary files /dev/null and b/docs/blog/searxpy3.png differ -- cgit v1.2.3 From b92631bf8c36a8b7fa1fada219428af8e2abb566 Mon Sep 17 00:00:00 2001 From: Adam Tauber Date: Mon, 12 Jun 2017 12:34:30 +0200 Subject: various mods: uwsgi setup and version update ++ py3 img src fix ++ new sphinx version - closes #939 --- docs/blog/python3.rst | 2 +- docs/conf.py | 6 +++--- docs/dev/install/installation.rst | 2 ++ 3 files changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/blog/python3.rst b/docs/blog/python3.rst index f9a058902..eb14a49eb 100644 --- a/docs/blog/python3.rst +++ b/docs/blog/python3.rst @@ -3,7 +3,7 @@ Introducing Python3 support As most operation systems are coming with Python3 installed by default. So it is time for searx to support Python3. But don't worry support of Python2.7 won't be dropped. -.. image:: hurray.png +.. image:: searxpy3.png :scale: 50 % :alt: hurray :align: center diff --git a/docs/conf.py b/docs/conf.py index 012499570..52aad6630 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,7 +49,7 @@ master_doc = 'index' # General information about the project. project = u'searx' -copyright = u'2015-2016, Adam Tauber' +copyright = u'2015-2017, Adam Tauber' author = u'Adam Tauber' # The version info for the project you're documenting, acts as replacement for @@ -57,9 +57,9 @@ author = u'Adam Tauber' # built documents. # # The short X.Y version. -version = '0.11.0' +version = '0.12.0' # The full version, including alpha/beta/rc tags. -release = '0.11.0' +release = '0.12.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index b02718fe3..e1ae3f2a1 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -99,6 +99,8 @@ this content: single-interpreter = true master = true plugin = python + lazy-apps = true + enable-threads = true # Module to import module = searx.webapp -- 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') 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 6cc9f5694979956fd54a695bff6d454ca17f721d Mon Sep 17 00:00:00 2001 From: Adam Tauber Date: Tue, 8 Aug 2017 15:19:02 +0200 Subject: [enh] add morty documentation --- docs/admin/morty.rst | 21 +++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 22 insertions(+) create mode 100644 docs/admin/morty.rst (limited to 'docs') diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst new file mode 100644 index 000000000..49e62bba9 --- /dev/null +++ b/docs/admin/morty.rst @@ -0,0 +1,21 @@ +How to setup result proxy +========================= + +By default searx can only act as an image proxy for result images, +but it is possible to proxify all the result URLs with an external service, +`morty `__. + +To use this feature, morty has to be installed and activated in searx's ``settings.yml``. + +Add the following snippet to your ``settings.yml`` and restart searx: + + +.. code:: yaml + + result_proxy: + url : http://127.0.0.1:3000/ + key : your_morty_proxy_key + +``url`` is the address of the running morty service + +``key`` is an optional argument, see `morty's README `__ for more information. diff --git a/docs/index.rst b/docs/index.rst index abd57f08c..7854fdb01 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,6 +40,7 @@ Administrator documentation dev/install/installation admin/api admin/filtron + admin/morty Developer documentation ----------------------- -- cgit v1.2.3 From 979dd3d96c91c0430adca7528cda18cc7e547211 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Tue, 22 Aug 2017 21:30:00 +0200 Subject: blog: add post about searx-admin --- docs/blog/admin.rst | 42 ++++++++++++++++++++++++++++++++++++++ docs/blog/blog.rst | 1 + docs/blog/searx-admin-engines.png | Bin 0 -> 50840 bytes 3 files changed, 43 insertions(+) create mode 100644 docs/blog/admin.rst create mode 100644 docs/blog/searx-admin-engines.png (limited to 'docs') diff --git a/docs/blog/admin.rst b/docs/blog/admin.rst new file mode 100644 index 000000000..18d5ed33b --- /dev/null +++ b/docs/blog/admin.rst @@ -0,0 +1,42 @@ +Searx admin interface: manage your instance from your browser +============================================================= + +One of the biggest advantages of searx is being extremely customizable. But at first it can be daunting to newcomers. +A barrier of taking advantage of this feature is our ugly settings file which is sometimes hard to understand and edit. + +To make self-hosting searx more accessible a new tool is introduced, called ``searx-admin``. +It is a web application which is capable of managing your instance and manipulating its settings via a web UI. +It aims to replace editing of ``settings.yml`` for less experienced administrators or people +who prefer graphical admin interfaces. + +.. figure:: searx-admin-engines.png + :scale: 50 % + :alt: Screenshot of engine list + :align: center + :figclass: align-center + + Configuration page of engines + + +Since ``searx-admin`` acts as a supervisor for searx, we have decided to implement it +as a standalone tool instead of part of searx. Another reason for making it a standalone +tool is that the codebase and dependencies of searx should not grow because of a fully optional feature, +which does not affect existing instances. + + +Installation +------------ + +Installation guide can be found in the repository of searx-admin: +https://github.com/kvch/searx-admin#installation--usage + +Acknowledgements +---------------- + +This development was sponsored by `NLnet Foundation`_. + +.. _NLnet Foundation: https://nlnet.nl/ + + +| Happy hacking. +| kvch // 2017.08.22 21:25 diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst index aad448c6b..77553d5cf 100644 --- a/docs/blog/blog.rst +++ b/docs/blog/blog.rst @@ -5,3 +5,4 @@ Blog :maxdepth: 1 python3 + admin diff --git a/docs/blog/searx-admin-engines.png b/docs/blog/searx-admin-engines.png new file mode 100644 index 000000000..610bacdf7 Binary files /dev/null and b/docs/blog/searx-admin-engines.png differ -- 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') 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 2134c7c6939ce4f20fbb6ffca330ad7af0ff673a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Wed, 17 Jan 2018 22:05:10 +0100 Subject: change python-pybabel to python-babel in package requirements Closes #1147 --- docs/dev/install/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index e1ae3f2a1..8b6bb69b0 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -15,7 +15,7 @@ Install packages: .. code:: sh - sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-pybabel zlib1g-dev libffi-dev libssl-dev + sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-babel zlib1g-dev libffi-dev libssl-dev Install searx: -- cgit v1.2.3 From 20e85275cbea356827bd71fc8136245d37b0f209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Tue, 23 Jan 2018 20:43:22 +0100 Subject: remove Gratipay and Flattr from sidebar --- docs/_themes/searx_theme/relations.html | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/_themes/searx_theme/relations.html b/docs/_themes/searx_theme/relations.html index b7539e5a1..5fb65cdd2 100644 --- a/docs/_themes/searx_theme/relations.html +++ b/docs/_themes/searx_theme/relations.html @@ -10,7 +10,5 @@
-- cgit v1.2.3 From 94af140318338ab6e7b064b3b26b5fb45523d17a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9o=20Bourrel?= Date: Thu, 30 Aug 2018 11:14:03 +0200 Subject: Update quickstart.rst Rename `build_grunt` to `grunt_build` as in manage.sh --- docs/dev/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index 92ef62385..e7d4baf46 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -89,7 +89,7 @@ After installing grunt, the files can be built using the following command: .. code:: sh - ./manage.sh build_grunt + ./manage.sh grunt_build -- cgit v1.2.3 From 10ebe8cec9d926ca1c7c19336bf60c1ee88d9300 Mon Sep 17 00:00:00 2001 From: tmikaeld Date: Sun, 21 Oct 2018 11:36:11 +0200 Subject: Added missing symlink instruction --- docs/dev/install/installation.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index 8b6bb69b0..6c3f773a5 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -150,6 +150,10 @@ content: } } +Create a symlink to sites-enabled: + +sudo ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx + Restart service: .. code:: sh -- cgit v1.2.3 From 77494166d2c61dcc5e62447e88e6d3bb4e5254c2 Mon Sep 17 00:00:00 2001 From: tmikaeld Date: Sun, 21 Oct 2018 11:42:00 +0200 Subject: Formatting... --- docs/dev/install/installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index 6c3f773a5..50b33a324 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -152,7 +152,9 @@ content: Create a symlink to sites-enabled: -sudo ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx +.. code:: sh + + sudo ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx Restart service: -- cgit v1.2.3 From 021e1da4c9a8eca7293ad62608cc55da5dfde73f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Wed, 23 Oct 2019 13:06:19 +0200 Subject: add post about introducing offline engines --- docs/blog/blog.rst | 1 + docs/blog/intro-offline.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 2 +- docs/dev/engine_overview.rst | 2 ++ 4 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 docs/blog/intro-offline.rst (limited to 'docs') diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst index 77553d5cf..2ccaaa5d3 100644 --- a/docs/blog/blog.rst +++ b/docs/blog/blog.rst @@ -6,3 +6,4 @@ Blog python3 admin + intro-offline diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst new file mode 100644 index 000000000..914521718 --- /dev/null +++ b/docs/blog/intro-offline.rst @@ -0,0 +1,65 @@ +Preparation for offline engines +=============================== + +Offline engines +--------------- + +To extend the functionality of searx, offline engines are going to be introduced. An offline engine is an engine which does not need Internet connection to perform a search and does not use HTTP to communicate. + +Offline engines can be configured as online engines, by adding those to the `engines` list of `settings.yml`. Thus, searx finds the engine file and imports it. + +Example skeleton for the new engines: + +.. code:: python + + from subprocess import PIPE, Popen + + categories = ['general'] + offline = True + + def init(settings): + pass + + def search(query, params): + process = Popen(['ls', query], stdout=PIPE) + return_code = process.wait() + if return_code != 0: + raise RuntimeError('non-zero return code', return_code) + + results = [] + line = process.stdout.readline() + while line: + result = parse_line(line) + results.append(results) + + line = process.stdout.readline() + + return results + + +Development progress +-------------------- + +First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: https://github.com/asciimoo/searx/wiki/Offline-engines + +In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests. + +As offline searches can return arbitrary results depending on the engine, the current result templates were insufficient to present such results. Thus, a new template is introduced which is caplable of presenting arbitrary key value pairs as a table. You can check out the pull request for more details: https://github.com/asciimoo/searx/pull/1700 + +Next steps +---------- + +Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines. + +Acknowledgement +--------------- + +This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ . + +.. _Search and Discovery Fund: https://nlnet.nl/discovery +.. _NLnet Foundation: https://nlnet.nl/ + + +| Happy hacking. +| kvch // 2019.10.21 17:03 + diff --git a/docs/conf.py b/docs/conf.py index 52aad6630..e71ea13a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,7 +49,7 @@ master_doc = 'index' # General information about the project. project = u'searx' -copyright = u'2015-2017, Adam Tauber' +copyright = u'2015-2019, Adam Tauber, Noémi Ványi' author = u'Adam Tauber' # The version info for the project you're documenting, acts as replacement for diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index d57ca5b38..a6867b5d0 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -41,6 +41,8 @@ engine file +----------------------+-----------+-----------------------------------------+ | time\_range\_support | boolean | support search time range | +----------------------+-----------+-----------------------------------------+ +| offline | boolean | engine runs offline | ++----------------------+-----------+-----------------------------------------+ settings.yml ~~~~~~~~~~~~ -- cgit v1.2.3 From 25fa7da6c8276ed8958793e1b88071eab6b413f5 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Dec 2019 15:27:27 +0100 Subject: doc: use customized pocoo theme (pallets-sphinx-themes) The old searx theme was a copy of the flask theme. In the meantime this theme is available from the python module pallets-sphinx-themes. This patch makes pallets-sphinx-themes as a (dev) requirement and drops most of the old and obsolete searx theme settings/files. Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 15 + docs/_themes/searx/theme.conf | 6 + docs/_themes/searx_theme/layout.html | 20 -- docs/_themes/searx_theme/relations.html | 14 - docs/_themes/searx_theme/static/style.css_t | 443 ---------------------------- docs/_themes/searx_theme/theme.conf | 7 - docs/conf.py | 383 +++--------------------- docs/index.rst | 1 + 8 files changed, 67 insertions(+), 822 deletions(-) create mode 100644 docs/_themes/searx/static/searx.css create mode 100644 docs/_themes/searx/theme.conf delete mode 100644 docs/_themes/searx_theme/layout.html delete mode 100644 docs/_themes/searx_theme/relations.html delete mode 100644 docs/_themes/searx_theme/static/style.css_t delete mode 100644 docs/_themes/searx_theme/theme.conf (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css new file mode 100644 index 000000000..ae59adead --- /dev/null +++ b/docs/_themes/searx/static/searx.css @@ -0,0 +1,15 @@ +@import url("pocoo.css"); + +a, a.reference, a.footnote-reference { + color: #004b6b; + border-color: #004b6b; +} + +a:hover { + color: #6d4100; + border-color: #6d4100; +} + +p.version-warning { + background-color: #004b6b; +} diff --git a/docs/_themes/searx/theme.conf b/docs/_themes/searx/theme.conf new file mode 100644 index 000000000..2d5f72e7d --- /dev/null +++ b/docs/_themes/searx/theme.conf @@ -0,0 +1,6 @@ +[theme] +inherit = pocoo +stylesheet = searx.css + +[options] +touch_icon = diff --git a/docs/_themes/searx_theme/layout.html b/docs/_themes/searx_theme/layout.html deleted file mode 100644 index edf70c1a8..000000000 --- a/docs/_themes/searx_theme/layout.html +++ /dev/null @@ -1,20 +0,0 @@ -{%- extends "basic/layout.html" %} -{%- block extrahead %} - {{ super() }} - {% if theme_touch_icon %} - - {% endif %} - - -{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block relbar1 %}{% endblock %} -{%- block sidebarsearch %}{% endblock %} -{%- block sidebarsourcelink %}{% endblock %} -{%- block sidebartoc %}{% endblock %} -{%- block footer %} -
- © Copyright {{ copyright }}. -
-{%- endblock %} diff --git a/docs/_themes/searx_theme/relations.html b/docs/_themes/searx_theme/relations.html deleted file mode 100644 index 5fb65cdd2..000000000 --- a/docs/_themes/searx_theme/relations.html +++ /dev/null @@ -1,14 +0,0 @@ -
-

Searx

- -
- -
diff --git a/docs/_themes/searx_theme/static/style.css_t b/docs/_themes/searx_theme/static/style.css_t deleted file mode 100644 index 0a312b76e..000000000 --- a/docs/_themes/searx_theme/static/style.css_t +++ /dev/null @@ -1,443 +0,0 @@ -/* - * flasky.css_t - * ~~~~~~~~~~~~ - * - * :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz. - * :license: Flask Design License, see LICENSE for details. - */ - -{% set page_width = '940px' %} -{% set sidebar_width = '220px' %} - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro'; - font-size: 17px; - background-color: white; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - width: {{ page_width }}; - margin: 30px auto 0 auto; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 {{ sidebar_width }}; -} - -div.sphinxsidebar { - width: {{ sidebar_width }}; - word-wrap: normal !important; - overflow-wrap: normal !important; -} - -hr { - border: 1px solid #B1B4B6; -} - -div.body { - background-color: #ffffff; - color: #3E4349; - padding: 0 30px 0 30px; -} - -img.floatingflask { - padding: 0 0 10px 10px; - float: right; -} - -div.footer { - width: {{ page_width }}; - margin: 20px auto 30px auto; - font-size: 14px; - color: #888; - text-align: right; -} - -div.footer a { - color: #888; -} - -div.sphinxsidebar a { - color: #444; - text-decoration: none; - border-bottom: 1px dotted #999; -} - -div.sphinxsidebar a:hover { - border-bottom: 1px solid #999; -} - -div.sphinxsidebarwrapper { - padding: 0 10px; -} - -div.sphinxsidebarwrapper p.logo { - padding: 0; - margin: -10px 0 0 -20px; - text-align: center; -} - -div.sphinxsidebar h3, -div.sphinxsidebar h4 { - font-family: 'Garamond', 'Georgia', serif; - color: #444; - font-size: 24px; - font-weight: normal; - margin: 0 0 5px 0; - padding: 0; -} - -div.sphinxsidebar h4 { - font-size: 20px; -} - -div.sphinxsidebar h3 a { - color: #444; -} - -div.sphinxsidebar p.logo a, -div.sphinxsidebar h3 a, -div.sphinxsidebar p.logo a:hover, -div.sphinxsidebar h3 a:hover { - border: none; -} - -div.sphinxsidebar p { - color: #555; - margin: 10px 0; -} - -div.sphinxsidebar ul { - margin: 10px 0; - padding: 0; - color: #000; -} - -div.sphinxsidebar input { - border: 1px solid #ccc; - font-family: 'Georgia', serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #004B6B; - text-decoration: underline; -} - -a:hover { - color: #6D4100; - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - margin: 30px 0px 10px 0px; - padding: 0; -} - -div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } -div.body h2 { font-size: 180%; } -div.body h3 { font-size: 150%; } -div.body h4 { font-size: 130%; } -div.body h5 { font-size: 100%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #ddd; - padding: 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - color: #444; - background: #eaeaea; -} - -div.body p, div.body dd, div.body li { - line-height: 1.4em; -} - -div.admonition { - background: #fafafa; - margin: 20px -30px; - padding: 10px 30px; - border-top: 1px solid #ccc; - border-bottom: 1px solid #ccc; -} - -div.admonition tt.xref, div.admonition a tt { - border-bottom: 1px solid #fafafa; -} - -dd div.admonition { - margin-left: -60px; - padding-left: 60px; -} - -div.admonition p.admonition-title { - font-family: 'Garamond', 'Georgia', serif; - font-weight: normal; - font-size: 24px; - margin: 0 0 10px 0; - padding: 0; - line-height: 1; -} - -div.admonition p.last { - margin-bottom: 0; -} - -div.highlight { - background-color: white; -} - -dt:target, .highlight { - background: #FAF3E8; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre, tt { - font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.9em; -} - -img.screenshot { -} - -tt.descname, tt.descclassname { - font-size: 0.95em; -} - -tt.descname { - padding-right: 0.08em; -} - -img.screenshot { - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils { - border: 1px solid #888; - -moz-box-shadow: 2px 2px 4px #eee; - -webkit-box-shadow: 2px 2px 4px #eee; - box-shadow: 2px 2px 4px #eee; -} - -table.docutils td, table.docutils th { - border: 1px solid #888; - padding: 0.25em 0.7em; -} - -table.field-list, table.footnote { - border: none; - -moz-box-shadow: none; - -webkit-box-shadow: none; - box-shadow: none; -} - -table.footnote { - margin: 15px 0; - width: 100%; - border: 1px solid #eee; - background: #fdfdfd; - font-size: 0.9em; -} - -table.footnote + table.footnote { - margin-top: -15px; - border-top: none; -} - -table.field-list th { - padding: 0 0.8em 0 0; -} - -table.field-list td { - padding: 0; -} - -table.footnote td.label { - width: 0px; - padding: 0.3em 0 0.3em 0.5em; -} - -table.footnote td { - padding: 0.3em 0.5em; -} - -dl { - margin: 0; - padding: 0; -} - -dl dd { - margin-left: 30px; -} - -blockquote { - margin: 0 0 0 30px; - padding: 0; -} - -ul, ol { - margin: 10px 0 10px 30px; - padding: 0; -} - -pre { - background: #eee; - padding: 7px 30px; - margin: 15px -30px; - line-height: 1.3em; -} - -dl pre, blockquote pre, li pre { - margin-left: -60px; - padding-left: 60px; -} - -dl dl pre { - margin-left: -90px; - padding-left: 90px; -} - -tt { - background-color: #ecf0f3; - color: #222; - /* padding: 1px 2px; */ -} - -tt.xref, a tt { - background-color: #FBFBFB; - border-bottom: 1px solid white; -} - -a.reference { - text-decoration: none; - border-bottom: 1px dotted #004B6B; -} - -a.reference:hover { - border-bottom: 1px solid #6D4100; -} - -a.footnote-reference { - text-decoration: none; - font-size: 0.7em; - vertical-align: top; - border-bottom: 1px dotted #004B6B; -} - -a.footnote-reference:hover { - border-bottom: 1px solid #6D4100; -} - -a:hover tt { - background: #EEE; -} - - -@media screen and (max-width: 600px) { - - div.document { - width: 100%; - - } - - div.documentwrapper { - margin-left: 0; - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - } - - div.bodywrapper { - margin-top: 0; - margin-right: 0; - margin-bottom: 0; - margin-left: 0; - } - - ul { - margin-left: 0; - } - - .document { - width: auto; - } - - .footer { - width: auto; - } - - .bodywrapper { - margin: 0; - } - - .footer { - width: auto; - } - - div.sphinxsidebar { - display: none; - } - -} - -div.sidebar_container, div.sidebar_container h1 { -} - -div.sidebar_container h1 { - padding: 0; - margin: 0; - font-size: 350%; - line-height: 100%; -} - -div.sidebar_container ul li { - padding: 2px 8px; - font-size: 0.9em; -} diff --git a/docs/_themes/searx_theme/theme.conf b/docs/_themes/searx_theme/theme.conf deleted file mode 100644 index 38f9aaa93..000000000 --- a/docs/_themes/searx_theme/theme.conf +++ /dev/null @@ -1,7 +0,0 @@ -[theme] -inherit = basic -stylesheet = style.css -pygments_style = flask_theme_support.FlaskyStyle - -[options] -touch_icon = diff --git a/docs/conf.py b/docs/conf.py index e71ea13a7..1ad1b3b22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,358 +1,65 @@ # -*- coding: utf-8 -*- -# -# searx documentation build configuration file, created by -# sphinx-quickstart on Tue Nov 17 17:12:13 2015. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. -import sys -import os -import shlex +import sys, os +from searx.version import VERSION_STRING +from pallets_sphinx_themes import ProjectLink -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# Project -------------------------------------------------------------- -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.viewcode', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. project = u'searx' copyright = u'2015-2019, Adam Tauber, Noémi Ványi' author = u'Adam Tauber' +release, version = VERSION_STRING, VERSION_STRING -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.12.0' -# The full version, including alpha/beta/rc tags. -release = '0.12.0' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None +# General -------------------------------------------------------------- -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +master_doc = "index" +source_suffix = '.rst' -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +extensions = [ + 'sphinx.ext.viewcode', + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "pallets_sphinx_themes", + "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst +] -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + # "flask": ("https://flask.palletsprojects.com/", None), + # "werkzeug": ("https://werkzeug.palletsprojects.com/", None), + # "jinja": ("https://jinja.palletsprojects.com/", None), +} +issues_github_path = "asciimoo/searx" -# -- Options for HTML output ---------------------------------------------- +# HTML ----------------------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. sys.path.append(os.path.abspath('_themes')) -html_theme_path = ['_themes'] -html_theme = 'searx_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' -# Output file base name for HTML help builder. -htmlhelp_basename = 'searxdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', +html_theme_path = ['_themes'] +html_theme = "searx" + +html_theme_options = {"index_sidebar_logo": True} +html_context = { + "project_links": [ + ProjectLink("Source", os.environ.get("GIT_URL", "https://github.com/asciimoo")), + ProjectLink("Wiki", "https://github.com/asciimoo/searx/wiki"), + ProjectLink("Public instances", "https://github.com/asciimoo/searx/wiki/Searx-instances"), + ProjectLink("Twitter", "https://twitter.com/Searx_engine"), + ] } +html_sidebars = { + "**": ["project.html", "relations.html", "searchbox.html"], +} +singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]} +html_static_path = ["static"] +html_logo = "static/img/searx_logo_small.png" +html_title = "Searx Documentation ({})".format("Searx-{}.tex".format(VERSION_STRING)) +html_show_sourcelink = False -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'searx.tex', u'searx Documentation', - u'Adam Tauber', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'searx', u'searx Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- +# LaTeX ---------------------------------------------------------------- -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'searx', u'searx Documentation', - author, 'searx', 'One line description of project.', - 'Miscellaneous'), +latex_documents = [ + (master_doc, "searx-{}.tex".format(VERSION_STRING), html_title, author, "manual") ] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# The basename for the epub file. It defaults to the project name. -#epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not optimized -# for small screen space, using the same theme for HTML and epub output is -# usually not wise. This defaults to 'epub', a theme designed to save visual -# space. -#epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images = False - -# Scale large images. -#epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' - -# If false, no index is generated. -#epub_use_index = True diff --git a/docs/index.rst b/docs/index.rst index 7854fdb01..38adf69f2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,6 +41,7 @@ Administrator documentation admin/api admin/filtron admin/morty + blog/blog Developer documentation ----------------------- -- cgit v1.2.3 From af2cae6d1d71859e867a9fbc5da604ef6a898794 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Dec 2019 16:48:36 +0100 Subject: doc: make use of sphinx.ext.extlinks & sphinx.ext.intersphinx - add sphinx extensions - patch documentation to make use of These modules help to simplify the reST markup of external references. BTW it helps to write more readable reST and form custom brands. Signed-off-by: Markus Heiser --- docs/blog/intro-offline.rst | 2 +- docs/conf.py | 14 +++++++++++++- docs/dev/engine_overview.rst | 13 ++++++------- docs/index.rst | 3 +-- docs/user/search_syntax.rst | 33 +++++++++++++++++++-------------- 5 files changed, 40 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst index 914521718..0def3e09a 100644 --- a/docs/blog/intro-offline.rst +++ b/docs/blog/intro-offline.rst @@ -40,7 +40,7 @@ Example skeleton for the new engines: Development progress -------------------- -First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: https://github.com/asciimoo/searx/wiki/Offline-engines +First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: :wiki:`Offline-engines`. In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests. diff --git a/docs/conf.py b/docs/conf.py index 1ad1b3b22..ee60e46e3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,6 +4,9 @@ import sys, os from searx.version import VERSION_STRING from pallets_sphinx_themes import ProjectLink +GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx") +SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me") + # Project -------------------------------------------------------------- project = u'searx' @@ -16,7 +19,16 @@ release, version = VERSION_STRING, VERSION_STRING master_doc = "index" source_suffix = '.rst' +# usage:: lorem :patch:`f373169` ipsum + +extlinks = {} +extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://') +extlinks['patch'] = (GIT_URL + '/commit/%s', '#') +extlinks['search'] = (SEARX_URL + '/%s', '#') +extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ') + extensions = [ + 'sphinx.ext.extlinks', 'sphinx.ext.viewcode', "sphinx.ext.autodoc", "sphinx.ext.intersphinx", @@ -43,7 +55,7 @@ html_theme = "searx" html_theme_options = {"index_sidebar_logo": True} html_context = { "project_links": [ - ProjectLink("Source", os.environ.get("GIT_URL", "https://github.com/asciimoo")), + ProjectLink("Source", GIT_URL), ProjectLink("Wiki", "https://github.com/asciimoo/searx/wiki"), ProjectLink("Public instances", "https://github.com/asciimoo/searx/wiki/Searx-instances"), ProjectLink("Twitter", "https://twitter.com/Searx_engine"), diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index a6867b5d0..937ca8880 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -8,8 +8,7 @@ so it uses different search engines to provide better results. Because there is no general search API which could be used for every search engine, an adapter has to be built between searx and the external search engines. Adapters are stored under the folder -`searx/engines -`__. +:origin:`searx/engines`. .. contents:: @@ -199,7 +198,7 @@ default +--------------------+---------------------------------------------------------------------------------------------------------------+ | content | string, general result-text | +--------------------+---------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, time of publish | +| publishedDate | :py:class:`datetime.datetime`, time of publish | +--------------------+---------------------------------------------------------------------------------------------------------------+ images @@ -218,7 +217,7 @@ to use this template, the parameter +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | content | *(partly implemented)* | +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, time of publish *(partly implemented)* | +| publishedDate | :py:class:`datetime.datetime`, time of publish *(partly implemented)* | +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | img\_src | string, url to the result image | +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ @@ -239,7 +238,7 @@ videos +--------------------+--------------------------------------------------------------------------------------------------------------+ | content | *(not implemented yet)* | +--------------------+--------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, time of publish | +| publishedDate | :py:class:`datetime.datetime`, time of publish | +--------------------+--------------------------------------------------------------------------------------------------------------+ | thumbnail | string, url to a small-preview image | +--------------------+--------------------------------------------------------------------------------------------------------------+ @@ -258,7 +257,7 @@ torrent +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | content | string, general result-text | +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, time of publish *(not implemented yet)* | +| publishedDate | :py:class:`datetime.datetime`, time of publish *(not implemented yet)* | +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ | seed | int, number of seeder | +------------------+---------------------------------------------------------------------------------------------------------------------------------------+ @@ -286,7 +285,7 @@ map +-------------------------+--------------------------------------------------------------------------------------------------------------+ | content | string, general result-text | +-------------------------+--------------------------------------------------------------------------------------------------------------+ -| publishedDate | `datetime.datetime `__, time of publish | +| publishedDate | :py:class:`datetime.datetime`, time of publish | +-------------------------+--------------------------------------------------------------------------------------------------------------+ | latitude | latitude of result (in decimal format) | +-------------------------+--------------------------------------------------------------------------------------------------------------+ diff --git a/docs/index.rst b/docs/index.rst index 38adf69f2..4b2f170cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,9 +5,8 @@ Search without being tracked. Searx is a free internet metasearch engine which aggregates results from more than 70 search services. Users are neither tracked nor profiled. Additionally, searx can be used over Tor for online anonymity. -Get started with searx by using one of the `public instances`_. If you don't trust anyone, you can set up your own, see :ref:`installation`. +Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`. -.. _public instances: https://github.com/asciimoo/searx/wiki/Searx-instances Features -------- diff --git a/docs/user/search_syntax.rst b/docs/user/search_syntax.rst index af26ea83c..90f901ba7 100644 --- a/docs/user/search_syntax.rst +++ b/docs/user/search_syntax.rst @@ -4,30 +4,35 @@ Search syntax Searx allows you to modify the default categories, engines and search language via the search query. -Category/engine prefix: ``!`` +Prefix ``!`` + to set Category/engine -Language prefix: ``:`` +Prefix: ``:`` + to set language -Prefix to add engines and categories to the currently selected -categories: ``?`` +Prefix: ``?`` + to add engines and categories to the currently selected categories -Abbrevations of the engines and languages are also accepted. -Engine/category modifiers are chainable and inclusive (e.g. with -`!it !ddg !wp qwer `_ -search in IT category **and** duckduckgo **and** wikipedia for ``qwer``). +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 `/preferences page `_ for the -list of engines, categories and languages. +See the :search:`/preferences page ` for the list of engines, +categories and languages. Examples ~~~~~~~~ Search in wikipedia for ``qwer``: -`!wp qwer `__ or -`!wikipedia qwer `_ + +- :search:`!wp qwer ` or +- :search:`!wikipedia qwer :search:` Image search: -`!images Cthulhu `_ + +- :search:`!images Cthulhu ` Custom language in wikipedia: -`:hu !wp hackerspace `_ + +- :search:`:hu !wp hackerspace ` -- cgit v1.2.3 From 0a7479f1942a9e5fa63f55eda0977ce777088c71 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Dec 2019 17:30:34 +0100 Subject: doc: [fix] WARNING: Could not lex literal_block as "json" docs/admin/filtron.rst:24: \ WARNING: Could not lex literal_block as "json". Highlighting skipped. Signed-off-by: Markus Heiser --- docs/admin/filtron.rst | 155 +++++++++++++++++++++++++++++-------------------- 1 file changed, 93 insertions(+), 62 deletions(-) (limited to 'docs') diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst index c422cb0a8..9e55d5968 100644 --- a/docs/admin/filtron.rst +++ b/docs/admin/filtron.rst @@ -23,68 +23,99 @@ An example configuration can be find below. This configuration limits the access .. code:: json - [ - { - "name": "search request", - "filters": ["Param:q", "Path=^(/|/search)$"], - "interval": , - "limit": , - "subrules": [ - { - "name": "roboagent limit", - "interval": , - "limit": , - "filters": ["Header:User-Agent=(curl|cURL|Wget|python-requests|Scrapy|FeedFetcher|Go-http-client)"], - "actions": [ - {"name": "block", - "params": {"message": "Rate limit exceeded"}} - ] - }, - { - "name": "botlimit", - "limit": 0, - "stop": true, - "filters": ["Header:User-Agent=(Googlebot|bingbot|Baiduspider|yacybot|YandexMobileBot|YandexBot|Yahoo! Slurp|MJ12bot|AhrefsBot|archive.org_bot|msnbot|MJ12bot|SeznamBot|linkdexbot|Netvibes|SMTBot|zgrab|James BOT)"], - "actions": [ - {"name": "block", - "params": {"message": "Rate limit exceeded"}} - ] - }, - { - "name": "IP limit", - "interval": , - "limit": , - "stop": true, - "aggregations": ["Header:X-Forwarded-For"], - "actions": [ - {"name": "block", - "params": {"message": "Rate limit exceeded"}} - ] - }, - { - "name": "rss/json limit", - "interval": , - "limit": , - "stop": true, - "filters": ["Param:format=(csv|json|rss)"], - "actions": [ - {"name": "block", - "params": {"message": "Rate limit exceeded"}} - ] - }, - { - "name": "useragent limit", - "interval": , - "limit": , - "aggregations": ["Header:User-Agent"], - "actions": [ - {"name": "block", - "params": {"message": "Rate limit exceeded"}} - ] - } + [{ + "name":"search request", + "filters":[ + "Param:q", + "Path=^(/|/search)$" + ], + "interval":"", + "limit":"", + "subrules":[ + { + "name":"roboagent limit", + "interval":"", + "limit":"", + "filters":[ + "Header:User-Agent=(curl|cURL|Wget|python-requests|Scrapy|FeedFetcher|Go-http-client)" + ], + "actions":[ + { + "name":"block", + "params":{ + "message":"Rate limit exceeded" + } + } ] - } - ] + }, + { + "name":"botlimit", + "limit":0, + "stop":true, + "filters":[ + "Header:User-Agent=(Googlebot|bingbot|Baiduspider|yacybot|YandexMobileBot|YandexBot|Yahoo! Slurp|MJ12bot|AhrefsBot|archive.org_bot|msnbot|MJ12bot|SeznamBot|linkdexbot|Netvibes|SMTBot|zgrab|James BOT)" + ], + "actions":[ + { + "name":"block", + "params":{ + "message":"Rate limit exceeded" + } + } + ] + }, + { + "name":"IP limit", + "interval":"", + "limit":"", + "stop":true, + "aggregations":[ + "Header:X-Forwarded-For" + ], + "actions":[ + { + "name":"block", + "params":{ + "message":"Rate limit exceeded" + } + } + ] + }, + { + "name":"rss/json limit", + "interval":"", + "limit":"", + "stop":true, + "filters":[ + "Param:format=(csv|json|rss)" + ], + "actions":[ + { + "name":"block", + "params":{ + "message":"Rate limit exceeded" + } + } + ] + }, + { + "name":"useragent limit", + "interval":"", + "limit":"", + "aggregations":[ + "Header:User-Agent" + ], + "actions":[ + { + "name":"block", + "params":{ + "message":"Rate limit exceeded" + } + } + ] + } + ] + }] @@ -101,7 +132,7 @@ It listens on 127.0.0.1:4004 and forwards filtered requests to 127.0.0.1:8888 by Use it along with ``nginx`` with the following example configuration. -.. code:: bash +.. code:: nginx location / { proxy_set_header Host $http_host; -- cgit v1.2.3 From 5b14772b203fa32a9a2c7a6951a3c17ff32b6d88 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Dec 2019 17:54:41 +0100 Subject: doc: installation.rst improve reST markup - normalize section header markup - limit all lines to a maximum of 79 characters - add option -H to the sudo command used in code blocks - place *WARNING* lines into a '.. warning::' admonition block - make use of ``literal`` markup for monospace rendering - drop useless indentation of lists [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Signed-off-by: Markus Heiser --- docs/dev/install/installation.rst | 156 ++++++++++++++++++++------------------ 1 file changed, 84 insertions(+), 72 deletions(-) (limited to 'docs') diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst index 50b33a324..239ce0704 100644 --- a/docs/dev/install/installation.rst +++ b/docs/dev/install/installation.rst @@ -1,5 +1,6 @@ .. _installation: +============ Installation ============ @@ -7,37 +8,44 @@ Installation :depth: 3 Basic installation ------------------- +================== -Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure to have enable universe repository. +Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure +to have enable universe repository. Install packages: .. code:: sh - sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-babel zlib1g-dev libffi-dev libssl-dev + $ sudo -H apt-get install \ + git build-essential libxslt-dev \ + python-dev python-virtualenv python-babel \ + zlib1g-dev libffi-dev libssl-dev Install searx: .. code:: sh cd /usr/local - sudo git clone https://github.com/asciimoo/searx.git - sudo useradd searx -d /usr/local/searx - sudo chown searx:searx -R /usr/local/searx + sudo -H git clone https://github.com/asciimoo/searx.git + sudo -H useradd searx -d /usr/local/searx + sudo -H chown searx:searx -R /usr/local/searx Install dependencies in a virtualenv: .. code:: sh - sudo -u searx -i cd /usr/local/searx - virtualenv searx-ve - . ./searx-ve/bin/activate - ./manage.sh update_packages + sudo -H -u searx -i + +.. code:: sh + + (searx)$ virtualenv searx-ve + (searx)$ . ./searx-ve/bin/activate + (searx)$ ./manage.sh update_packages Configuration -------------- +============== .. code:: sh @@ -46,7 +54,7 @@ Configuration Edit searx/settings.yml if necessary. Check ------ +===== Start searx: @@ -68,18 +76,19 @@ You can exit the virtualenv and the searx user bash (enter exit command twice). uwsgi ------ +===== Install packages: .. code:: sh - sudo apt-get install uwsgi uwsgi-plugin-python + sudo -H apt-get install \ + uwsgi uwsgi-plugin-python -Create the configuration file /etc/uwsgi/apps-available/searx.ini with -this content: +Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this +content: -:: +.. code:: ini [uwsgi] # Who will run the code @@ -119,22 +128,22 @@ Activate the uwsgi application and restart: /etc/init.d/uwsgi restart Web server ----------- +========== with nginx -^^^^^^^^^^ +---------- If nginx is not installed (uwsgi will not work with the package nginx-light): .. code:: sh - sudo apt-get install nginx + sudo -H apt-get install nginx Hosted at / -""""""""""" +~~~~~~~~~~~ -Create the configuration file /etc/nginx/sites-available/searx with this +Create the configuration file ``/etc/nginx/sites-available/searx`` with this content: .. code:: nginx @@ -154,20 +163,20 @@ Create a symlink to sites-enabled: .. code:: sh - sudo ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx + sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx Restart service: .. code:: sh - sudo service nginx restart - sudo service uwsgi restart + sudo -H service nginx restart + sudo -H service uwsgi restart from subdirectory URL (/searx) -"""""""""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add this configuration in the server config file -/etc/nginx/sites-enabled/default: +``/etc/nginx/sites-enabled/default``: .. code:: nginx @@ -183,10 +192,8 @@ Add this configuration in the server config file } -OR - -using reverse proxy -(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.) +**OR** using reverse proxy (Please, note that reverse proxy advised to be used +in case of single-user or low-traffic instances.) .. code:: nginx @@ -200,9 +207,9 @@ using reverse proxy } -Enable base\_url in searx/settings.yml +Enable ``base_url`` in ``searx/settings.yml`` -:: +.. code:: yaml base_url : http://your.domain.tld/searx/ @@ -210,18 +217,18 @@ Restart service: .. code:: sh - sudo service nginx restart - sudo service uwsgi restart + sudo -H service nginx restart + sudo -H service uwsgi restart disable logs -~~~~~~~~~~~~ +^^^^^^^^^^^^ for better privacy you can disable nginx logs about searx. -how to proceed: below ``uwsgi_pass`` in -/etc/nginx/sites-available/default add +how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` +add: -:: +.. code:: nginx access_log /dev/null; error_log /dev/null; @@ -230,19 +237,19 @@ Restart service: .. code:: sh - sudo service nginx restart + sudo -H service nginx restart with apache -^^^^^^^^^^^ +----------- Add wsgi mod: .. code:: sh - sudo apt-get install libapache2-mod-uwsgi - sudo a2enmod uwsgi + sudo -H apt-get install libapache2-mod-uwsgi + sudo -H a2enmod uwsgi -Add this configuration in the file /etc/apache2/apache2.conf: +Add this configuration in the file ``/etc/apache2/apache2.conf``: .. code:: apache @@ -252,27 +259,26 @@ Add this configuration in the file /etc/apache2/apache2.conf: uWSGISocket /run/uwsgi/app/searx/socket -Note that if your instance of searx is not at the root, you should -change ```` by the location of your instance, like -````. +Note that if your instance of searx is not at the root, you should change +```` by the location of your instance, like ````. Restart Apache: .. code:: sh - sudo /etc/init.d/apache2 restart + sudo -H /etc/init.d/apache2 restart disable logs -"""""""""""" +~~~~~~~~~~~~ For better privacy you can disable Apache logs. -WARNING: not tested +.. warning:: -WARNING: you can only disable logs for the whole (virtual) server not -for a specific path. + You can only disable logs for the whole (virtual) server not for a specific + path. -Go back to /etc/apache2/apache2.conf and above ```` add: +Go back to ``/etc/apache2/apache2.conf`` and above ```` add: .. code:: apache @@ -282,24 +288,30 @@ Restart Apache: .. code:: sh - sudo /etc/init.d/apache2 restart + sudo -H /etc/init.d/apache2 restart How to update -------------- +============= .. code:: sh cd /usr/local/searx - sudo -u searx -i - . ./searx-ve/bin/activate - git stash - git pull origin master - git stash apply - ./manage.sh update_packages - sudo service uwsgi restart + sudo -H -u searx -i + +.. code:: sh + + (searx)$ . ./searx-ve/bin/activate + (searx)$ git stash + (searx)$ git pull origin master + (searx)$ git stash apply + (searx)$ ./manage.sh update_packages + +.. code:: sh + + sudo -H service uwsgi restart Docker ------- +====== Make sure you have installed Docker. For instance, you can deploy searx like this: @@ -308,22 +320,22 @@ Make sure you have installed Docker. For instance, you can deploy searx like thi docker pull wonderfall/searx docker run -d --name searx -p $PORT:8888 wonderfall/searx -Go to http://localhost:$PORT. - -See https://hub.docker.com/r/wonderfall/searx/ for more informations. +Go to ``http://localhost:$PORT``. -It's also possible to build searx from the embedded Dockerfile. +See https://hub.docker.com/r/wonderfall/searx/ for more informations. It's also +possible to build searx from the embedded Dockerfile. .. code:: sh - git clone https://github.com/asciimoo/searx.git - cd searx - docker build -t whatever/searx . + git clone https://github.com/asciimoo/searx.git + cd searx + docker build -t whatever/searx . References ========== - * https://about.okhin.fr/posts/Searx/ with some additions +* https://about.okhin.fr/posts/Searx/ with some additions - * How to: `Setup searx in a couple of hours with a free SSL certificate `__ +* How to: `Setup searx in a couple of hours with a free SSL certificate + `__ -- 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/admin/api.rst | 160 +++++++------- docs/admin/filtron.rst | 55 ++--- docs/admin/morty.rst | 19 +- docs/blog/admin.rst | 53 ++--- docs/blog/blog.rst | 1 + docs/blog/intro-offline.rst | 64 +++--- docs/blog/python3.rst | 48 +++-- docs/conf.py | 8 +- docs/dev/contribution_guide.rst | 103 +++++---- docs/dev/engine_overview.rst | 453 ++++++++++++++++++---------------------- docs/dev/plugins.rst | 45 ++-- docs/dev/quickstart.rst | 92 ++++---- docs/dev/search_api.rst | 226 ++++++-------------- docs/dev/translation.rst | 44 ++-- docs/index.rst | 34 +-- docs/user/own-instance.rst | 70 +++++-- docs/user/search_syntax.rst | 10 +- 17 files changed, 716 insertions(+), 769 deletions(-) (limited to 'docs') diff --git a/docs/admin/api.rst b/docs/admin/api.rst index 8d6162247..7804a8664 100644 --- a/docs/admin/api.rst +++ b/docs/admin/api.rst @@ -1,94 +1,96 @@ .. _adminapi: +================== Administration API ------------------- +================== Get configuration data -~~~~~~~~~~~~~~~~~~~~~~ +====================== -.. code:: sh +.. code:: http - GET /config + GET /config HTTP/1.1 Sample response -``````````````` +--------------- + +.. code:: json + + { + "autocomplete": "", + "categories": [ + "map", + "it", + "images", + ], + "default_locale": "", + "default_theme": "oscar", + "engines": [ + { + "categories": [ + "map" + ], + "enabled": true, + "name": "openstreetmap", + "shortcut": "osm" + }, + { + "categories": [ + "it" + ], + "enabled": true, + "name": "arch linux wiki", + "shortcut": "al" + }, + { + "categories": [ + "images" + ], + "enabled": true, + "name": "google images", + "shortcut": "goi" + }, + { + "categories": [ + "it" + ], + "enabled": false, + "name": "bitbucket", + "shortcut": "bb" + }, + ], + "instance_name": "searx", + "locales": { + "de": "Deutsch (German)", + "en": "English", + "eo": "Esperanto (Esperanto)", + }, + "plugins": [ + { + "enabled": true, + "name": "HTTPS rewrite" + }, + { + "enabled": false, + "name": "Vim-like hotkeys" + } + ], + "safe_search": 0 + } -.. code:: sh - - { - "autocomplete": "", - "categories": [ - "map", - "it", - "images", - ], - "default_locale": "", - "default_theme": "oscar", - "engines": [ - { - "categories": [ - "map" - ], - "enabled": true, - "name": "openstreetmap", - "shortcut": "osm" - }, - { - "categories": [ - "it" - ], - "enabled": true, - "name": "arch linux wiki", - "shortcut": "al" - }, - { - "categories": [ - "images" - ], - "enabled": true, - "name": "google images", - "shortcut": "goi" - }, - { - "categories": [ - "it" - ], - "enabled": false, - "name": "bitbucket", - "shortcut": "bb" - }, - ], - "instance_name": "searx", - "locales": { - "de": "Deutsch (German)", - "en": "English", - "eo": "Esperanto (Esperanto)", - }, - "plugins": [ - { - "enabled": true, - "name": "HTTPS rewrite" - }, - { - "enabled": false, - "name": "Vim-like hotkeys" - } - ], - "safe_search": 0 - } Embed search bar ----------------- +================ -The search bar can be embedded into websites. Just paste the example into the HTML of the site. -URL of the searx instance and values are customizable. +The search bar can be embedded into websites. Just paste the example into the +HTML of the site. URL of the searx instance and values are customizable. .. code:: html - -
- - - - - -
+ +
+ + + + + +
diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst index 9e55d5968..07dcb9bc5 100644 --- a/docs/admin/filtron.rst +++ b/docs/admin/filtron.rst @@ -1,25 +1,26 @@ +========================== How to protect an instance ========================== -Searx depens on external search services. To avoid the abuse of these services it is advised to limit the number of requests processed by searx. - -An application firewall, ``filtron`` solves exactly this problem. Information on how to install it can be found at the `project page of filtron `__. - -Sample configuration of filtron -------------------------------- +Searx depens on external search services. To avoid the abuse of these services +it is advised to limit the number of requests processed by searx. -An example configuration can be find below. This configuration limits the access of +An application firewall, ``filtron`` solves exactly this problem. Information +on how to install it can be found at the `project page of filtron +`__. - * scripts or applications (roboagent limit) - * webcrawlers (botlimit) - - * IPs which send too many requests (IP limit) - - * too many json, csv, etc. requests (rss/json limit) +Sample configuration of filtron +=============================== - * the same UserAgent of if too many requests (useragent limit) +An example configuration can be find below. This configuration limits the access +of: +- scripts or applications (roboagent limit) +- webcrawlers (botlimit) +- IPs which send too many requests (IP limit) +- too many json, csv, etc. requests (rss/json limit) +- the same UserAgent of if too many requests (useragent limit) .. code:: json @@ -120,26 +121,28 @@ An example configuration can be find below. This configuration limits the access Route request through filtron ------------------------------ +============================= Filtron can be started using the following command: -.. code:: bash +.. code:: sh - $ filtron -rules rules.json + $ filtron -rules rules.json -It listens on 127.0.0.1:4004 and forwards filtered requests to 127.0.0.1:8888 by default. +It listens on ``127.0.0.1:4004`` and forwards filtered requests to +``127.0.0.1:8888`` by default. Use it along with ``nginx`` with the following example configuration. .. code:: nginx - location / { - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Scheme $scheme; - proxy_pass http://127.0.0.1:4004/; - } + location / { + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Scheme $scheme; + proxy_pass http://127.0.0.1:4004/; + } -Requests are coming from port 4004 going through filtron and then forwarded to port 8888 where a searx is being run. +Requests are coming from port 4004 going through filtron and then forwarded to +port 8888 where a searx is being run. diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst index 49e62bba9..7d7b34492 100644 --- a/docs/admin/morty.rst +++ b/docs/admin/morty.rst @@ -1,14 +1,17 @@ +========================= How to setup result proxy ========================= -By default searx can only act as an image proxy for result images, -but it is possible to proxify all the result URLs with an external service, -`morty `__. +.. _morty: https://github.com/asciimoo/morty +.. _morty's README: https://github.com/asciimoo/morty -To use this feature, morty has to be installed and activated in searx's ``settings.yml``. +By default searx can only act as an image proxy for result images, but it is +possible to proxify all the result URLs with an external service, morty_. -Add the following snippet to your ``settings.yml`` and restart searx: +To use this feature, morty has to be installed and activated in searx's +``settings.yml``. +Add the following snippet to your ``settings.yml`` and restart searx: .. code:: yaml @@ -16,6 +19,8 @@ Add the following snippet to your ``settings.yml`` and restart searx: url : http://127.0.0.1:3000/ key : your_morty_proxy_key -``url`` is the address of the running morty service +``url`` + Is the address of the running morty service. -``key`` is an optional argument, see `morty's README `__ for more information. +``key`` + Is an optional argument, see `morty's README`_ for more information. diff --git a/docs/blog/admin.rst b/docs/blog/admin.rst index 18d5ed33b..e95316192 100644 --- a/docs/blog/admin.rst +++ b/docs/blog/admin.rst @@ -1,42 +1,43 @@ -Searx admin interface: manage your instance from your browser +============================================================= +Searx admin interface ============================================================= -One of the biggest advantages of searx is being extremely customizable. But at first it can be daunting to newcomers. -A barrier of taking advantage of this feature is our ugly settings file which is sometimes hard to understand and edit. +.. _searx-admin: https://github.com/kvch/searx-admin#searx-admin +.. _NLnet Foundation: https://nlnet.nl/ -To make self-hosting searx more accessible a new tool is introduced, called ``searx-admin``. -It is a web application which is capable of managing your instance and manipulating its settings via a web UI. -It aims to replace editing of ``settings.yml`` for less experienced administrators or people -who prefer graphical admin interfaces. + manage your instance from your browser -.. figure:: searx-admin-engines.png - :scale: 50 % - :alt: Screenshot of engine list - :align: center - :figclass: align-center - - Configuration page of engines +.. sidebar:: Installation + Installation guide can be found in the repository of searx-admin_. -Since ``searx-admin`` acts as a supervisor for searx, we have decided to implement it -as a standalone tool instead of part of searx. Another reason for making it a standalone -tool is that the codebase and dependencies of searx should not grow because of a fully optional feature, -which does not affect existing instances. +One of the biggest advantages of searx is being extremely customizable. But at +first it can be daunting to newcomers. A barrier of taking advantage of this +feature is our ugly settings file which is sometimes hard to understand and +edit. +To make self-hosting searx more accessible a new tool is introduced, called +``searx-admin``. It is a web application which is capable of managing your +instance and manipulating its settings via a web UI. It aims to replace editing +of ``settings.yml`` for less experienced administrators or people who prefer +graphical admin interfaces. -Installation ------------- +.. figure:: searx-admin-engines.png + :alt: Screenshot of engine list -Installation guide can be found in the repository of searx-admin: -https://github.com/kvch/searx-admin#installation--usage + Configuration page of engines -Acknowledgements ----------------- +Since ``searx-admin`` acts as a supervisor for searx, we have decided to +implement it as a standalone tool instead of part of searx. Another reason for +making it a standalone tool is that the codebase and dependencies of searx +should not grow because of a fully optional feature, which does not affect +existing instances. -This development was sponsored by `NLnet Foundation`_. -.. _NLnet Foundation: https://nlnet.nl/ +Acknowledgements +================ +This development was sponsored by `NLnet Foundation`_. | Happy hacking. | kvch // 2017.08.22 21:25 diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst index 2ccaaa5d3..52fa3f126 100644 --- a/docs/blog/blog.rst +++ b/docs/blog/blog.rst @@ -1,3 +1,4 @@ +==== Blog ==== diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst index 0def3e09a..f6e90de3a 100644 --- a/docs/blog/intro-offline.rst +++ b/docs/blog/intro-offline.rst @@ -1,58 +1,70 @@ +=============================== Preparation for offline engines =============================== Offline engines ---------------- +=============== -To extend the functionality of searx, offline engines are going to be introduced. An offline engine is an engine which does not need Internet connection to perform a search and does not use HTTP to communicate. +To extend the functionality of searx, offline engines are going to be +introduced. An offline engine is an engine which does not need Internet +connection to perform a search and does not use HTTP to communicate. -Offline engines can be configured as online engines, by adding those to the `engines` list of `settings.yml`. Thus, searx finds the engine file and imports it. +Offline engines can be configured as online engines, by adding those to the +`engines` list of :origin:`settings.yml `. Thus, searx +finds the engine file and imports it. Example skeleton for the new engines: .. code:: python - from subprocess import PIPE, Popen + from subprocess import PIPE, Popen - categories = ['general'] - offline = True + categories = ['general'] + offline = True - def init(settings): - pass + def init(settings): + pass - def search(query, params): - process = Popen(['ls', query], stdout=PIPE) - return_code = process.wait() - if return_code != 0: - raise RuntimeError('non-zero return code', return_code) + def search(query, params): + process = Popen(['ls', query], stdout=PIPE) + return_code = process.wait() + if return_code != 0: + raise RuntimeError('non-zero return code', return_code) - results = [] - line = process.stdout.readline() - while line: - result = parse_line(line) - results.append(results) + results = [] + line = process.stdout.readline() + while line: + result = parse_line(line) + results.append(results) - line = process.stdout.readline() + line = process.stdout.readline() - return results + return results Development progress --------------------- +==================== -First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: :wiki:`Offline-engines`. +First, a proposal has been created as a Github issue. Then it was moved to the +wiki as a design document. You can read it here: :wiki:`Offline-engines`. -In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests. +In this development step, searx core was prepared to accept and perform offline +searches. Offline search requests are scheduled together with regular offline +requests. -As offline searches can return arbitrary results depending on the engine, the current result templates were insufficient to present such results. Thus, a new template is introduced which is caplable of presenting arbitrary key value pairs as a table. You can check out the pull request for more details: https://github.com/asciimoo/searx/pull/1700 +As offline searches can return arbitrary results depending on the engine, the +current result templates were insufficient to present such results. Thus, a new +template is introduced which is caplable of presenting arbitrary key value pairs +as a table. You can check out the pull request for more details see +:pull:`1700`. Next steps ----------- +========== Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines. Acknowledgement ---------------- +=============== This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ . diff --git a/docs/blog/python3.rst b/docs/blog/python3.rst index eb14a49eb..5bb7f1c80 100644 --- a/docs/blog/python3.rst +++ b/docs/blog/python3.rst @@ -1,7 +1,17 @@ -Introducing Python3 support -=========================== +============================ +Introducing Python 3 support +============================ -As most operation systems are coming with Python3 installed by default. So it is time for searx to support Python3. But don't worry support of Python2.7 won't be dropped. +.. _Python 2.7 clock: https://pythonclock.org/ + +.. sidebar:: Python 2.7 to 3 upgrade + + This chapter exists of historical reasons. Python 2.7 release schedule ends + (`Python 2.7 clock`_) after 11 years Python 3 exists + +As most operation systems are coming with Python3 installed by default. So it is +time for searx to support Python3. But don't worry support of Python2.7 won't be +dropped. .. image:: searxpy3.png :scale: 50 % @@ -9,13 +19,14 @@ As most operation systems are coming with Python3 installed by default. So it is :align: center -How to run searx using Python3 ------------------------------- +How to run searx using Python 3 +=============================== -Please make sure that you run at least Python3.5. +Please make sure that you run at least Python 3.5. -To run searx, first a Python3 virtualenv should be created. After entering the virtualenv, -dependencies must be installed. Then run searx with python3 instead of the usual python command. +To run searx, first a Python3 virtualenv should be created. After entering the +virtualenv, dependencies must be installed. Then run searx with python3 instead +of the usual python command. .. code:: sh @@ -25,25 +36,28 @@ dependencies must be installed. Then run searx with python3 instead of the usual python3 searx/webapp.py -If you want to run searx using Python2.7, you don't have to do anything differently as before. +If you want to run searx using Python2.7, you don't have to do anything +differently as before. Fun facts ---------- +========= - 115 files were changed when implementing the support for both Python versions. -- All of the dependencies was compatible except for the robotframework used for browser tests. Thus, these tests were migrated to splinter. So from now on both versions are being tested on Travis and can be tested locally. +- All of the dependencies was compatible except for the robotframework used for + browser tests. Thus, these tests were migrated to splinter. So from now on + both versions are being tested on Travis and can be tested locally. -If you found bugs... --------------------- +If you found bugs +================= -...please open an issue on `GitHub`_. Make sure that you mention your Python version in your issue, -so we can investigate it properly. +Please open an issue on `GitHub`_. Make sure that you mention your Python +version in your issue, so we can investigate it properly. .. _GitHub: https://github.com/asciimoo/searx/issues -Acknowledgement ---------------- +Acknowledgment +============== This development was sponsored by `NLnet Foundation`_. diff --git a/docs/conf.py b/docs/conf.py index ee60e46e3..5186d0123 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,12 +20,16 @@ master_doc = "index" source_suffix = '.rst' # usage:: lorem :patch:`f373169` ipsum - extlinks = {} + +# upstream links +extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ') +extlinks['pull'] = ('https://github.com/asciimoo/searx/pull/%s', 'PR ') + +# links to custom brand extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://') extlinks['patch'] = (GIT_URL + '/commit/%s', '#') extlinks['search'] = (SEARX_URL + '/%s', '#') -extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ') extensions = [ 'sphinx.ext.extlinks', diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 65e587294..9414de2c9 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -1,66 +1,68 @@ +================= How to contribute ------------------ +================= Prime directives: Privacy, Hackability -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +====================================== -Searx has two prime directives, privacy-by-design and hackability. The +Searx has two prime directives, **privacy-by-design and hackability** . The hackability comes in three levels: -- support of search engines -- plugins to alter search behaviour -- hacking searx itself +- support of search engines +- plugins to alter search behaviour +- hacking searx itself -Note the lack of "world domination" among the directives. -Searx has no intention of wide mass-adoption, rounded -corners, etc. The prime directive "privacy" deserves a separate -chapter, as it's quite uncommon unfortunately. +Note the lack of "world domination" among the directives. Searx has no +intention of wide mass-adoption, rounded corners, etc. The prime directive +"privacy" deserves a separate chapter, as it's quite uncommon unfortunately. Privacy-by-design -^^^^^^^^^^^^^^^^^ +----------------- -Searx was born out of the need for a privacy-respecting search tool -which can be extended easily to maximize both its search and its -privacy protecting capabilities. +Searx was born out of the need for a **privacy-respecting** search tool which +can be extended easily to maximize both, its search and its privacy protecting +capabilities. -A few widely used features work differently or turned off by default or not implemented -at all as a consequence of privacy-by-design. +A few widely used features work differently or turned off by default or not +implemented at all **as a consequence of privacy-by-design**. -If a feature reduces the privacy preserving aspects of searx, it -should be switched off by default or should not implemented at all. -There are plenty of search engines already providing such features. -If a feature reduces the protection of searx, users must be -informed about the effect of choosing to enable it. Features -that protect privacy but differ from the expectations of the -user should also be explained. +If a feature reduces the privacy preserving aspects of searx, it should be +switched off by default or should not implemented at all. There are plenty of +search engines already providing such features. If a feature reduces the +protection of searx, users must be informed about the effect of choosing to +enable it. Features that protect privacy but differ from the expectations of +the user should also be explained. -Also, if you think that something works weird with searx, -it's might be because of the tool you use is designed in a way to interfere with -the privacy respect. Submitting a bugreport to the vendor of the tool that -misbehaves might be a good feedback to reconsider the disrespect to -its customers (e.g. GET vs POST requests in various browsers). +Also, if you think that something works weird with searx, it's might be because +of the tool you use is designed in a way to interfere with the privacy respect. +Submitting a bugreport to the vendor of the tool that misbehaves might be a good +feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST`` +requests in various browsers). -Remember the other prime directive of searx is to be hackable, so if the -above privacy concerns do not fancy you, simply fork it. +Remember the other prime directive of searx is to be hackable, so if the above +privacy concerns do not fancy you, simply fork it. -Happy hacking. + *Happy hacking.* Code -~~~~ +==== + +.. _PEP8: https://www.python.org/dev/peps/pep-0008/ + In order to submit a patch, please follow the steps below: - Follow coding conventions. - - PEP8 standards apply, except the convention of line length - + - PEP8_ standards apply, except the convention of line length - Maximum line length is 120 characters -- Check if your code breaks existing tests. If so, update the tests or fix your code. +- Check if your code breaks existing tests. If so, update the tests or fix your + code. - If your code can be unit-tested, add unit tests. -- Add yourself to the AUTHORS file. +- Add yourself to the :origin:`AUTHORS.rst` file. - Create a pull request. @@ -68,31 +70,20 @@ For more help on getting started with searx development, see :ref:`devquickstart Translation -~~~~~~~~~~~ +=========== -Translation currently takes place on -`transifex `__. +Translation currently takes place on :ref:`transifex `. -**Please, do not update translation files in the repo.** +.. caution:: -Documentation -~~~~~~~~~~~~~ + Please, do not update translation files in the repo. -The documentation is built using Sphinx. So in order to be able to generate the required -files, you have to install it on your system. (It can be installed easily using pip.) -1. Checkout the gh-pages branch. - -2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder. - -3. Build the documentation using Sphinx. - -4. Add the updated and created files of these extension: - - - .rst +Documentation +============= - - .html +.. admonition:: ToDo - - .txt + docs are no longer in gh-branch -6. Create a pull request. + Update this chapter and document the /docs workflow!! diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 937ca8880..92405dc64 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -1,21 +1,25 @@ + +.. _engines-dev: + +=============== Engine overview =============== +.. _metasearch-engine: https://en.wikipedia.org/wiki/Metasearch_engine -searx is a `metasearch-engine `__, -so it uses different search engines to provide better results. - -Because there is no general search API which could be used for every -search engine, an adapter has to be built between searx and the -external search engines. Adapters are stored under the folder -:origin:`searx/engines`. +searx is a metasearch-engine_, so it uses different search engines to provide +better results. +Because there is no general search API which could be used for every search +engine, an adapter has to be built between searx and the external search +engines. Adapters are stored under the folder :origin:`searx/engines`. .. contents:: :depth: 3 + :backlinks: entry general engine configuration ----------------------------- +============================ It is required to tell searx the type of results the engine provides. The arguments can be set in the engine file or in the settings file @@ -23,292 +27,239 @@ arguments can be set in the engine file or in the settings file the ones in the engine file. It does not matter if an option is stored in the engine file or in the -settings. However, the standard way is the following: +settings. However, the standard way is the following: engine file -~~~~~~~~~~~ - -+----------------------+-----------+-----------------------------------------+ -| argument | type | information | -+======================+===========+=========================================+ -| categories | list | pages, in which the engine is working | -+----------------------+-----------+-----------------------------------------+ -| paging | boolean | support multible pages | -+----------------------+-----------+-----------------------------------------+ -| language\_support | boolean | support language choosing | -+----------------------+-----------+-----------------------------------------+ -| time\_range\_support | boolean | support search time range | -+----------------------+-----------+-----------------------------------------+ -| offline | boolean | engine runs offline | -+----------------------+-----------+-----------------------------------------+ +----------- + +======================= =========== =========================================== +argument type information +======================= =========== =========================================== +categories list pages, in which the engine is working +paging boolean support multible pages +language_support boolean support language choosing +time_range_support boolean support search time range +offline boolean engine runs offline +======================= =========== =========================================== + settings.yml -~~~~~~~~~~~~ - -+------------+----------+-----------------------------------------------+ -| argument | type | information | -+============+==========+===============================================+ -| name | string | name of search-engine | -+------------+----------+-----------------------------------------------+ -| engine | string | name of searx-engine (filename without .py) | -+------------+----------+-----------------------------------------------+ -| shortcut | string | shortcut of search-engine | -+------------+----------+-----------------------------------------------+ -| timeout | string | specific timeout for search-engine | -+------------+----------+-----------------------------------------------+ +------------ + +======================= =========== =========================================== +argument type information +======================= =========== =========================================== +name string name of search-engine +engine string name of searx-engine + (filename without ``.py``) +shortcut string shortcut of search-engine +timeout string specific timeout for search-engine +======================= =========== =========================================== + overrides -~~~~~~~~~ - -A few of the options have default values in the engine, but are -often overwritten by the settings. If ``None`` is assigned to an option -in the engine file, it has to be redefined in the settings, -otherwise searx will not start with that engine. - -The naming of overrides is arbitrary. But the recommended -overrides are the following: - -+-----------------------+----------+----------------------------------------------------------------+ -| argument | type | information | -+=======================+==========+================================================================+ -| base\_url | string | base-url, can be overwritten to use same engine on other URL | -+-----------------------+----------+----------------------------------------------------------------+ -| number\_of\_results | int | maximum number of results per request | -+-----------------------+----------+----------------------------------------------------------------+ -| language | string | ISO code of language and country like en\_US | -+-----------------------+----------+----------------------------------------------------------------+ -| api\_key | string | api-key if required by engine | -+-----------------------+----------+----------------------------------------------------------------+ +--------- + +A few of the options have default values in the engine, but are often +overwritten by the settings. If ``None`` is assigned to an option in the engine +file, it has to be redefined in the settings, otherwise searx will not start +with that engine. + +The naming of overrides is arbitrary. But the recommended overrides are the +following: + +======================= =========== =========================================== +argument type information +======================= =========== =========================================== +base_url string base-url, can be overwritten to use same + engine on other URL +number_of_results int maximum number of results per request +language string ISO code of language and country like en_US +api_key string api-key if required by engine +======================= =========== =========================================== example code -~~~~~~~~~~~~ +------------ .. code:: python - # engine dependent config - categories = ['general'] - paging = True - language_support = True + # engine dependent config + categories = ['general'] + paging = True + language_support = True + making a request ----------------- +================ -To perform a search an URL have to be specified. In addition to -specifying an URL, arguments can be passed to the query. +To perform a search an URL have to be specified. In addition to specifying an +URL, arguments can be passed to the query. passed arguments -~~~~~~~~~~~~~~~~ +---------------- -These arguments can be used to construct the search query. Furthermore, +These arguments can be used to construct the search query. Furthermore, parameters with default value can be redefined for special purposes. -+----------------------+------------+------------------------------------------------------------------------+ -| argument | type | default-value, information | -+======================+============+========================================================================+ -| url | string | ``''`` | -+----------------------+------------+------------------------------------------------------------------------+ -| method | string | ``'GET'`` | -+----------------------+------------+------------------------------------------------------------------------+ -| headers | set | ``{}`` | -+----------------------+------------+------------------------------------------------------------------------+ -| data | set | ``{}`` | -+----------------------+------------+------------------------------------------------------------------------+ -| cookies | set | ``{}`` | -+----------------------+------------+------------------------------------------------------------------------+ -| verify | boolean | ``True`` | -+----------------------+------------+------------------------------------------------------------------------+ -| headers.User-Agent | string | a random User-Agent | -+----------------------+------------+------------------------------------------------------------------------+ -| category | string | current category, like ``'general'`` | -+----------------------+------------+------------------------------------------------------------------------+ -| started | datetime | current date-time | -+----------------------+------------+------------------------------------------------------------------------+ -| pageno | int | current pagenumber | -+----------------------+------------+------------------------------------------------------------------------+ -| language | string | specific language code like ``'en_US'``, or ``'all'`` if unspecified | -+----------------------+------------+------------------------------------------------------------------------+ +====================== ============ ======================================================================== +argument type default-value, information +====================== ============ ======================================================================== +url string ``''`` +method string ``'GET'`` +headers set ``{}`` +data set ``{}`` +cookies set ``{}`` +verify boolean ``True`` +headers.User-Agent string a random User-Agent +category string current category, like ``'general'`` +started datetime current date-time +pageno int current pagenumber +language string specific language code like ``'en_US'``, or ``'all'`` if unspecified +====================== ============ ======================================================================== parsed arguments -~~~~~~~~~~~~~~~~ - -The function ``def request(query, params):`` always returns the -``params`` variable. Inside searx, the following paramters can be -used to specify a search request: - -+------------+-----------+---------------------------------------------------------+ -| argument | type | information | -+============+===========+=========================================================+ -| url | string | requested url | -+------------+-----------+---------------------------------------------------------+ -| method | string | HTTP request method | -+------------+-----------+---------------------------------------------------------+ -| headers | set | HTTP header information | -+------------+-----------+---------------------------------------------------------+ -| data | set | HTTP data information (parsed if ``method != 'GET'``) | -+------------+-----------+---------------------------------------------------------+ -| cookies | set | HTTP cookies | -+------------+-----------+---------------------------------------------------------+ -| verify | boolean | Performing SSL-Validity check | -+------------+-----------+---------------------------------------------------------+ +---------------- + +The function ``def request(query, params):`` always returns the ``params`` +variable. Inside searx, the following paramters can be used to specify a search +request: + +============ =========== ========================================================= +argument type information +============ =========== ========================================================= +url string requested url +method string HTTP request method +headers set HTTP header information +data set HTTP data information (parsed if ``method != 'GET'``) +cookies set HTTP cookies +verify boolean Performing SSL-Validity check +============ =========== ========================================================= + example code -~~~~~~~~~~~~ +------------ .. code:: python - # search-url - base_url = 'https://example.com/' - search_string = 'search?{query}&page={page}' + # search-url + base_url = 'https://example.com/' + search_string = 'search?{query}&page={page}' - # do search-request - def request(query, params): - search_path = search_string.format( - query=urlencode({'q': query}), - page=params['pageno']) + # do search-request + def request(query, params): + search_path = search_string.format( + query=urlencode({'q': query}), + page=params['pageno']) - params['url'] = base_url + search_path + params['url'] = base_url + search_path + + return params - return params returned results ----------------- +================ -Searx is able to return results of different media-types. -Currently the following media-types are supported: +Searx is able to return results of different media-types. Currently the +following media-types are supported: -- default -- images -- videos -- torrent -- map +- default_ +- images_ +- videos_ +- torrent_ +- map_ -To set another media-type as default, the parameter -``template`` must be set to the desired type. +To set another media-type as default, the parameter ``template`` must be set to +the desired type. default -~~~~~~~ - -+--------------------+---------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+===============================================================================================================+ -| url | string, url of the result | -+--------------------+---------------------------------------------------------------------------------------------------------------+ -| title | string, title of the result | -+--------------------+---------------------------------------------------------------------------------------------------------------+ -| content | string, general result-text | -+--------------------+---------------------------------------------------------------------------------------------------------------+ -| publishedDate | :py:class:`datetime.datetime`, time of publish | -+--------------------+---------------------------------------------------------------------------------------------------------------+ +------- + +========================= ===================================================== +result-parameter information +========================= ===================================================== +url string, url of the result +title string, title of the result +content string, general result-text +publishedDate :py:class:`datetime.datetime`, time of publish +========================= ===================================================== images -~~~~~~ - -to use this template, the parameter - -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+=======================================================================================================================================+ -| template | is set to ``images.html`` | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, url to the result site | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, title of the result *(partly implemented)* | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| content | *(partly implemented)* | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | :py:class:`datetime.datetime`, time of publish *(partly implemented)* | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| img\_src | string, url to the result image | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| thumbnail\_src | string, url to a small-preview image | -+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +------ + +To use this template, the parameter: + +========================= ===================================================== +result-parameter information +========================= ===================================================== +template is set to ``images.html`` +url string, url to the result site +title string, title of the result *(partly implemented)* +content *(partly implemented)* +publishedDate :py:class:`datetime.datetime`, + time of publish *(partly implemented)* +img\_src string, url to the result image +thumbnail\_src string, url to a small-preview image +========================= ===================================================== videos -~~~~~~ - -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+====================+==============================================================================================================+ -| template | is set to ``videos.html`` | -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| url | string, url of the result | -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| title | string, title of the result | -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| content | *(not implemented yet)* | -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| publishedDate | :py:class:`datetime.datetime`, time of publish | -+--------------------+--------------------------------------------------------------------------------------------------------------+ -| thumbnail | string, url to a small-preview image | -+--------------------+--------------------------------------------------------------------------------------------------------------+ +------ + +========================= ===================================================== +result-parameter information +========================= ===================================================== +template is set to ``videos.html`` +url string, url of the result +title string, title of the result +content *(not implemented yet)* +publishedDate :py:class:`datetime.datetime`, time of publish +thumbnail string, url to a small-preview image +========================= ===================================================== torrent -~~~~~~~ - -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+==================+=======================================================================================================================================+ -| template | is set to ``torrent.html`` | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| url | string, url of the result | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| title | string, title of the result | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| content | string, general result-text | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| publishedDate | :py:class:`datetime.datetime`, time of publish *(not implemented yet)* | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| seed | int, number of seeder | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| leech | int, number of leecher | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| filesize | int, size of file in bytes | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| files | int, number of files | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| magnetlink | string, `magnetlink `__ of the result | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| torrentfile | string, torrentfile of the result | -+------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +------- + +.. _magnetlink: https://en.wikipedia.org/wiki/Magnet_URI_scheme + +========================= ===================================================== +result-parameter information +========================= ===================================================== +template is set to ``torrent.html`` +url string, url of the result +title string, title of the result +content string, general result-text +publishedDate :py:class:`datetime.datetime`, + time of publish *(not implemented yet)* +seed int, number of seeder +leech int, number of leecher +filesize int, size of file in bytes +files int, number of files +magnetlink string, magnetlink_ of the result +torrentfile string, torrentfile of the result +========================= ===================================================== map -~~~ - -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| result-parameter | information | -+=========================+==============================================================================================================+ -| url | string, url of the result | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| title | string, title of the result | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| content | string, general result-text | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| publishedDate | :py:class:`datetime.datetime`, time of publish | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| latitude | latitude of result (in decimal format) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| longitude | longitude of result (in decimal format) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| boundingbox | boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| geojson | geojson of result (http://geojson.org) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| osm.type | type of osm-object (if OSM-Result) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| osm.id | id of osm-object (if OSM-Result) | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.name | name of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.road | street name of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.house\_number | house number of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.locality | city, place of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.postcode | postcode of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ -| address.country | country of object | -+-------------------------+--------------------------------------------------------------------------------------------------------------+ - +--- + +========================= ===================================================== +result-parameter information +========================= ===================================================== +url string, url of the result +title string, title of the result +content string, general result-text +publishedDate :py:class:`datetime.datetime`, time of publish +latitude latitude of result (in decimal format) +longitude longitude of result (in decimal format) +boundingbox boundingbox of result (array of 4. values + ``[lat-min, lat-max, lon-min, lon-max]``) +geojson geojson of result (http://geojson.org) +osm.type type of osm-object (if OSM-Result) +osm.id id of osm-object (if OSM-Result) +address.name name of object +address.road street name of object +address.house_number house number of object +address.locality city, place of object +address.postcode postcode of object +address.country country of object +========================= ===================================================== diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst index 1d77f8611..e97bbeb4a 100644 --- a/docs/dev/plugins.rst +++ b/docs/dev/plugins.rst @@ -1,45 +1,48 @@ +======= Plugins -------- +======= -Plugins can extend or replace functionality of various components of -searx. +Plugins can extend or replace functionality of various components of searx. Example plugin -~~~~~~~~~~~~~~ +============== .. code:: python - name = 'Example plugin' - description = 'This plugin extends the suggestions with the word "example"' - default_on = False # disabled by default + name = 'Example plugin' + description = 'This plugin extends the suggestions with the word "example"' + default_on = False # disabled by default - js_dependencies = tuple() # optional, list of static js files - css_dependencies = tuple() # optional, list of static css files + js_dependencies = tuple() # optional, list of static js files + css_dependencies = tuple() # optional, list of static css files - # attach callback to the post search hook - # request: flask request object - # ctx: the whole local context of the post search hook - def post_search(request, ctx): - ctx['search'].suggestions.add('example') - return True + # attach callback to the post search hook + # request: flask request object + # ctx: the whole local context of the post search hook + def post_search(request, ctx): + ctx['search'].suggestions.add('example') + return True Plugin entry points -~~~~~~~~~~~~~~~~~~~ +=================== -Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin. +Entry points (hooks) define when a plugin runs. Right now only three hooks are +implemented. So feel free to implement a hook if it fits the behaviour of your +plugin. Pre search hook -``````````````` +--------------- Runs BEFORE the search request. Function to implement: ``pre_search`` Post search hook -```````````````` +---------------- Runs AFTER the search request. Function to implement: ``post_search`` Result hook -``````````` +----------- -Runs when a new result is added to the result list. Function to implement: ``on_result`` +Runs when a new result is added to the result list. Function to implement: +``on_result`` diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index e7d4baf46..a4a37a266 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -1,17 +1,18 @@ .. _devquickstart: +====================== Development Quickstart ----------------------- +====================== -This quickstart guide gets your environment set up with searx. Furthermore, it gives a -short introduction to the new manage.sh script. +This quickstart guide gets your environment set up with searx. Furthermore, it +gives a short introduction to the ``manage.sh`` script. How to setup your development environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================= -First, clone the source code of searx to the desired folder. In this case the source -is cloned to ~/myprojects/searx. Then create and activate the searx-ve -virtualenv and install the required packages using manage.sh. +First, clone the source code of searx to the desired folder. In this case the +source is cloned to ``~/myprojects/searx``. Then create and activate the +searx-ve virtualenv and install the required packages using manage.sh. .. code:: sh @@ -24,85 +25,86 @@ virtualenv and install the required packages using manage.sh. How to run tests -~~~~~~~~~~~~~~~~ +================ -Tests can be run using the manage.sh script. - -Following tests and checks are available: +Tests can be run using the ``manage.sh`` script. Following tests and checks are +available: - Unit tests - - Selenium tests - - PEP8 validation - - Unit test coverage check For example unit tests are run with the command below: .. code:: sh - ./manage.sh unit_tests + ./manage.sh unit_tests -For further test options, please consult the help of the manage.sh script. +For further test options, please consult the help of the ``manage.sh`` script. How to compile styles and javascript -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==================================== + +.. _less: http://lesscss.org/ +.. _NodeJS: https://nodejs.org How to build styles -^^^^^^^^^^^^^^^^^^^ +------------------- -Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt. +Less_ is required to build the styles of searx. Less_ can be installed using +either NodeJS_ or Apt. .. code:: sh - sudo apt-get install nodejs - sudo npm install -g less - + sudo -H apt-get install nodejs + sudo -H npm install -g less OR .. code:: sh - sudo apt-get install node-less + sudo -H apt-get install node-less -After satisfying the requirements styles can be build using manage.sh +After satisfying the requirements styles can be build using ``manage.sh`` .. code:: sh - ./manage.sh styles + ./manage.sh styles How to build the source of the oscar theme -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +========================================== -Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first -Node has to be installed. +.. _grunt: https://gruntjs.com/ + +Grunt_ must be installed in order to build the javascript sources. It depends on +NodeJS, so first Node has to be installed. .. code:: sh - sudo apt-get install nodejs - sudo npm install -g grunt-cli + sudo -H apt-get install nodejs + sudo -H npm install -g grunt-cli -After installing grunt, the files can be built using the following command: +After installing grunt, the files can be built using the following command: .. code:: sh - ./manage.sh grunt_build - + ./manage.sh grunt_build Tips for debugging/development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Turn on debug logging - Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea - to turn on debug logging. When debug logging is enabled a stack trace appears, - instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting - ``debug: False`` to ``debug: True`` in settings.yml. - -2. Run ``./manage.sh tests`` before creating a PR. - Failing build on Travis is common because of PEP8 checks. So a new commit must be created - containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run - locally before creating a PR. +============================== + +Turn on debug logging + Whether you are working on a new engine or trying to eliminate a bug, it is + always a good idea to turn on debug logging. When debug logging is enabled a + stack trace appears, instead of the cryptic ``Internal Server Error`` + message. It can be turned on by setting ``debug: False`` to ``debug: True`` in + :origin:`settings.yml `. + +Run ``./manage.sh tests`` before creating a PR. + Failing build on Travis is common because of PEP8 checks. So a new commit + must be created containing these format fixes. This phase can be skipped if + ``./manage.sh tests`` is run locally before creating a PR. 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 diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst index ab4dd98cb..86c4c843b 100644 --- a/docs/dev/translation.rst +++ b/docs/dev/translation.rst @@ -1,28 +1,36 @@ +.. _translation: + +=========== Translation =========== -Requirements ------------- +.. _searx@transifex: https://www.transifex.com/asciimoo/searx/ + +Translation currently takes place on `searx@transifex`_ - * Transifex account +Requirements +============ - * Installed CLI tool of Transifex +* Transifex account +* Installed CLI tool of Transifex Init Transifex project ----------------------- +====================== -After installing ``transifex`` using pip, run the following command to initialize the project. +After installing ``transifex`` using pip, run the following command to +initialize the project. -.. code:: shell +.. code:: sh - tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/ + tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/ -After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it into the configuration file. +After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it +into the configuration file. Create a configuration file for ``tx`` named ``$HOME/.tx/config``. -.. code:: shell +.. code:: ini [main] host = https://www.transifex.com @@ -42,20 +50,22 @@ Then run ``tx set``: Update translations -------------------- +=================== To retrieve the latest translations, pull it from Transifex. -.. code:: shell +.. code:: sh - tx pull -a + tx pull -a -Then check the new languages. If strings translated are not enough, delete those folders, because -those should not be compiled. Call the command below to compile the ``.po`` files. +Then check the new languages. If strings translated are not enough, delete those +folders, because those should not be compiled. Call the command below to compile +the ``.po`` files. .. code:: shell - pybabel compile -d searx/translations + pybabel compile -d searx/translations -After the compilation is finished commit the ``.po`` and ``.mo`` files and create a PR. +After the compilation is finished commit the ``.po`` and ``.mo`` files and +create a PR. diff --git a/docs/index.rst b/docs/index.rst index 4b2f170cf..8fd37cbdc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,22 +3,24 @@ Welcome to searx Search without being tracked. -Searx is a free internet metasearch engine which aggregates results from more than 70 search services. Users are neither tracked nor profiled. Additionally, searx can be used over Tor for online anonymity. - -Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`. - - -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) - - Hosted by organisations, such as La Quadrature du Net, which promote digital rights +.. 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) + - Hosted by organizations, such as *La Quadrature du Net*, which promote + digital rights + +Searx is a free internet metasearch engine which aggregates results from more +than 70 search services. Users are neither tracked nor profiled. Additionally, +searx can be used over Tor for online anonymity. + +Get started with searx by using one of the :wiki:`Searx-instances`. If you +don't trust anyone, you can set up your own, see :ref:`installation`. User documentation diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst index 555f82cca..a2f736562 100644 --- a/docs/user/own-instance.rst +++ b/docs/user/own-instance.rst @@ -1,43 +1,77 @@ +=========================== Why use a private instance? =========================== -"Is it worth to run my own instance?" is a common question among searx users. Before answering this question, see what options a searx user has. +"Is it worth to run my own instance?" is a common question among searx users. +Before answering this question, see what options a searx 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 searx 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. +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 searx 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 searx protects its users. +To gain more insight on how these instances work let's dive into how searx +protects its users. How does searx protect privacy? -------------------------------- +=============================== -Searx 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: +Searx 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) + 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 searx can be configured to use proxy or Tor. `Result proxy `__ is supported, too. +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 searx can be +configured to use proxy or Tor. `Result proxy +`__ is supported, too. + +Searx 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. -Searx 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, he/she has to trust the administrator of that instance. -This means that the user of the public instance does not know whether his/her requests are logged, aggregated and sent or sold to a third party. +If someone uses a public instance, he/she has to trust the administrator of that +instance. This means that the user of the public instance does not know whether +his/her 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. +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 own instances, everything is in their control: the source code, logging settings and private data. Unknown instance administrators do not have to be trusted. +If users run their 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 searx 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. +Furthermore, as the default settings of their instance is editable, there is no +need to use cookies to tailor searx 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 searx are available to users no matter what kind of instance they use. +Always use an instance which is operated by people you trust. The privacy +features of searx are available to users no matter what kind of instance they +use. -If someone is on the go or just wants to try searx 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. +If someone is on the go or just wants to try searx 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/search_syntax.rst b/docs/user/search_syntax.rst index 90f901ba7..b738c7274 100644 --- a/docs/user/search_syntax.rst +++ b/docs/user/search_syntax.rst @@ -1,8 +1,12 @@ + +.. _search-syntax: + +============= Search syntax ============= -Searx allows you to modify the default categories, engines and search -language via the search query. +Searx allows you to modify the default categories, engines and search language +via the search query. Prefix ``!`` to set Category/engine @@ -22,7 +26,7 @@ See the :search:`/preferences page ` for the list of engines, categories and languages. Examples -~~~~~~~~ +======== Search in wikipedia for ``qwer``: -- cgit v1.2.3 From 04eeeb53a1215315d8027ac99978b560f45d5521 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 12 Dec 2019 19:48:42 +0100 Subject: doc: moved reST sources in the right folder (much clearer) Signed-off-by: Markus Heiser --- docs/admin/index.rst | 11 ++ docs/admin/installation.rst | 341 ++++++++++++++++++++++++++++++++++++++ docs/blog/blog.rst | 10 -- docs/blog/index.rst | 10 ++ docs/dev/index.rst | 13 ++ docs/dev/install/installation.rst | 341 -------------------------------------- docs/index.rst | 38 +---- docs/user/index.rst | 9 + 8 files changed, 390 insertions(+), 383 deletions(-) create mode 100644 docs/admin/index.rst create mode 100644 docs/admin/installation.rst delete mode 100644 docs/blog/blog.rst create mode 100644 docs/blog/index.rst create mode 100644 docs/dev/index.rst delete mode 100644 docs/dev/install/installation.rst create mode 100644 docs/user/index.rst (limited to 'docs') diff --git a/docs/admin/index.rst b/docs/admin/index.rst new file mode 100644 index 000000000..f3a995769 --- /dev/null +++ b/docs/admin/index.rst @@ -0,0 +1,11 @@ +=========================== +Administrator documentation +=========================== + +.. toctree:: + :maxdepth: 1 + + installation + api + filtron + morty diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst new file mode 100644 index 000000000..239ce0704 --- /dev/null +++ b/docs/admin/installation.rst @@ -0,0 +1,341 @@ +.. _installation: + +============ +Installation +============ + +.. contents:: + :depth: 3 + +Basic installation +================== + +Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure +to have enable universe repository. + +Install packages: + +.. code:: sh + + $ sudo -H apt-get install \ + git build-essential libxslt-dev \ + python-dev python-virtualenv python-babel \ + zlib1g-dev libffi-dev libssl-dev + +Install searx: + +.. code:: sh + + cd /usr/local + sudo -H git clone https://github.com/asciimoo/searx.git + sudo -H useradd searx -d /usr/local/searx + sudo -H chown searx:searx -R /usr/local/searx + +Install dependencies in a virtualenv: + +.. code:: sh + + cd /usr/local/searx + sudo -H -u searx -i + +.. code:: sh + + (searx)$ virtualenv searx-ve + (searx)$ . ./searx-ve/bin/activate + (searx)$ ./manage.sh update_packages + +Configuration +============== + +.. code:: sh + + sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml + +Edit searx/settings.yml if necessary. + +Check +===== + +Start searx: + +.. code:: sh + + python searx/webapp.py + +Go to http://localhost:8888 + +If everything works fine, disable the debug option in settings.yml: + +.. code:: sh + + sed -i -e "s/debug : True/debug : False/g" searx/settings.yml + +At this point searx is not demonized ; uwsgi allows this. + +You can exit the virtualenv and the searx user bash (enter exit command +twice). + +uwsgi +===== + +Install packages: + +.. code:: sh + + sudo -H apt-get install \ + uwsgi uwsgi-plugin-python + +Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this +content: + +.. code:: ini + + [uwsgi] + # Who will run the code + uid = searx + gid = searx + + # disable logging for privacy + disable-logging = true + + # Number of workers (usually CPU count) + workers = 4 + + # The right granted on the created socket + chmod-socket = 666 + + # Plugin to use and interpretor config + single-interpreter = true + master = true + plugin = python + lazy-apps = true + enable-threads = true + + # Module to import + module = searx.webapp + + # Virtualenv and python path + virtualenv = /usr/local/searx/searx-ve/ + pythonpath = /usr/local/searx/ + chdir = /usr/local/searx/searx/ + +Activate the uwsgi application and restart: + +.. code:: sh + + cd /etc/uwsgi/apps-enabled + ln -s ../apps-available/searx.ini + /etc/init.d/uwsgi restart + +Web server +========== + +with nginx +---------- + +If nginx is not installed (uwsgi will not work with the package +nginx-light): + +.. code:: sh + + sudo -H apt-get install nginx + +Hosted at / +~~~~~~~~~~~ + +Create the configuration file ``/etc/nginx/sites-available/searx`` with this +content: + +.. code:: nginx + + server { + listen 80; + server_name searx.example.com; + root /usr/local/searx; + + location / { + include uwsgi_params; + uwsgi_pass unix:/run/uwsgi/app/searx/socket; + } + } + +Create a symlink to sites-enabled: + +.. code:: sh + + sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + sudo -H service uwsgi restart + +from subdirectory URL (/searx) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add this configuration in the server config file +``/etc/nginx/sites-enabled/default``: + +.. code:: nginx + + location = /searx { rewrite ^ /searx/; } + location /searx { + try_files $uri @searx; + } + location @searx { + uwsgi_param SCRIPT_NAME /searx; + include uwsgi_params; + uwsgi_modifier1 30; + uwsgi_pass unix:/run/uwsgi/app/searx/socket; + } + + +**OR** using reverse proxy (Please, note that reverse proxy advised to be used +in case of single-user or low-traffic instances.) + +.. code:: nginx + + location /searx { + proxy_pass http://127.0.0.1:8888; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Scheme $scheme; + proxy_set_header X-Script-Name /searx; + proxy_buffering off; + } + + +Enable ``base_url`` in ``searx/settings.yml`` + +.. code:: yaml + + base_url : http://your.domain.tld/searx/ + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + sudo -H service uwsgi restart + +disable logs +^^^^^^^^^^^^ + +for better privacy you can disable nginx logs about searx. + +how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` +add: + +.. code:: nginx + + access_log /dev/null; + error_log /dev/null; + +Restart service: + +.. code:: sh + + sudo -H service nginx restart + +with apache +----------- + +Add wsgi mod: + +.. code:: sh + + sudo -H apt-get install libapache2-mod-uwsgi + sudo -H a2enmod uwsgi + +Add this configuration in the file ``/etc/apache2/apache2.conf``: + +.. code:: apache + + + Options FollowSymLinks Indexes + SetHandler uwsgi-handler + uWSGISocket /run/uwsgi/app/searx/socket + + +Note that if your instance of searx is not at the root, you should change +```` by the location of your instance, like ````. + +Restart Apache: + +.. code:: sh + + sudo -H /etc/init.d/apache2 restart + +disable logs +~~~~~~~~~~~~ + +For better privacy you can disable Apache logs. + +.. warning:: + + You can only disable logs for the whole (virtual) server not for a specific + path. + +Go back to ``/etc/apache2/apache2.conf`` and above ```` add: + +.. code:: apache + + CustomLog /dev/null combined + +Restart Apache: + +.. code:: sh + + sudo -H /etc/init.d/apache2 restart + +How to update +============= + +.. code:: sh + + cd /usr/local/searx + sudo -H -u searx -i + +.. code:: sh + + (searx)$ . ./searx-ve/bin/activate + (searx)$ git stash + (searx)$ git pull origin master + (searx)$ git stash apply + (searx)$ ./manage.sh update_packages + +.. code:: sh + + sudo -H service uwsgi restart + +Docker +====== + +Make sure you have installed Docker. For instance, you can deploy searx like this: + +.. code:: sh + + docker pull wonderfall/searx + docker run -d --name searx -p $PORT:8888 wonderfall/searx + +Go to ``http://localhost:$PORT``. + +See https://hub.docker.com/r/wonderfall/searx/ for more informations. It's also +possible to build searx from the embedded Dockerfile. + +.. code:: sh + + git clone https://github.com/asciimoo/searx.git + cd searx + docker build -t whatever/searx . + +References +========== + +* https://about.okhin.fr/posts/Searx/ with some additions + +* How to: `Setup searx in a couple of hours with a free SSL certificate + `__ + diff --git a/docs/blog/blog.rst b/docs/blog/blog.rst deleted file mode 100644 index 52fa3f126..000000000 --- a/docs/blog/blog.rst +++ /dev/null @@ -1,10 +0,0 @@ -==== -Blog -==== - -.. toctree:: - :maxdepth: 1 - - python3 - admin - intro-offline diff --git a/docs/blog/index.rst b/docs/blog/index.rst new file mode 100644 index 000000000..52fa3f126 --- /dev/null +++ b/docs/blog/index.rst @@ -0,0 +1,10 @@ +==== +Blog +==== + +.. toctree:: + :maxdepth: 1 + + python3 + admin + intro-offline diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 000000000..8e18066ca --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,13 @@ +======================= +Developer documentation +======================= + +.. toctree:: + :maxdepth: 1 + + quickstart + contribution_guide + engine_overview + search_api + plugins + translation diff --git a/docs/dev/install/installation.rst b/docs/dev/install/installation.rst deleted file mode 100644 index 239ce0704..000000000 --- a/docs/dev/install/installation.rst +++ /dev/null @@ -1,341 +0,0 @@ -.. _installation: - -============ -Installation -============ - -.. contents:: - :depth: 3 - -Basic installation -================== - -Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure -to have enable universe repository. - -Install packages: - -.. code:: sh - - $ sudo -H apt-get install \ - git build-essential libxslt-dev \ - python-dev python-virtualenv python-babel \ - zlib1g-dev libffi-dev libssl-dev - -Install searx: - -.. code:: sh - - cd /usr/local - sudo -H git clone https://github.com/asciimoo/searx.git - sudo -H useradd searx -d /usr/local/searx - sudo -H chown searx:searx -R /usr/local/searx - -Install dependencies in a virtualenv: - -.. code:: sh - - cd /usr/local/searx - sudo -H -u searx -i - -.. code:: sh - - (searx)$ virtualenv searx-ve - (searx)$ . ./searx-ve/bin/activate - (searx)$ ./manage.sh update_packages - -Configuration -============== - -.. code:: sh - - sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml - -Edit searx/settings.yml if necessary. - -Check -===== - -Start searx: - -.. code:: sh - - python searx/webapp.py - -Go to http://localhost:8888 - -If everything works fine, disable the debug option in settings.yml: - -.. code:: sh - - sed -i -e "s/debug : True/debug : False/g" searx/settings.yml - -At this point searx is not demonized ; uwsgi allows this. - -You can exit the virtualenv and the searx user bash (enter exit command -twice). - -uwsgi -===== - -Install packages: - -.. code:: sh - - sudo -H apt-get install \ - uwsgi uwsgi-plugin-python - -Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this -content: - -.. code:: ini - - [uwsgi] - # Who will run the code - uid = searx - gid = searx - - # disable logging for privacy - disable-logging = true - - # Number of workers (usually CPU count) - workers = 4 - - # The right granted on the created socket - chmod-socket = 666 - - # Plugin to use and interpretor config - single-interpreter = true - master = true - plugin = python - lazy-apps = true - enable-threads = true - - # Module to import - module = searx.webapp - - # Virtualenv and python path - virtualenv = /usr/local/searx/searx-ve/ - pythonpath = /usr/local/searx/ - chdir = /usr/local/searx/searx/ - -Activate the uwsgi application and restart: - -.. code:: sh - - cd /etc/uwsgi/apps-enabled - ln -s ../apps-available/searx.ini - /etc/init.d/uwsgi restart - -Web server -========== - -with nginx ----------- - -If nginx is not installed (uwsgi will not work with the package -nginx-light): - -.. code:: sh - - sudo -H apt-get install nginx - -Hosted at / -~~~~~~~~~~~ - -Create the configuration file ``/etc/nginx/sites-available/searx`` with this -content: - -.. code:: nginx - - server { - listen 80; - server_name searx.example.com; - root /usr/local/searx; - - location / { - include uwsgi_params; - uwsgi_pass unix:/run/uwsgi/app/searx/socket; - } - } - -Create a symlink to sites-enabled: - -.. code:: sh - - sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - sudo -H service uwsgi restart - -from subdirectory URL (/searx) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add this configuration in the server config file -``/etc/nginx/sites-enabled/default``: - -.. code:: nginx - - location = /searx { rewrite ^ /searx/; } - location /searx { - try_files $uri @searx; - } - location @searx { - uwsgi_param SCRIPT_NAME /searx; - include uwsgi_params; - uwsgi_modifier1 30; - uwsgi_pass unix:/run/uwsgi/app/searx/socket; - } - - -**OR** using reverse proxy (Please, note that reverse proxy advised to be used -in case of single-user or low-traffic instances.) - -.. code:: nginx - - location /searx { - proxy_pass http://127.0.0.1:8888; - proxy_set_header Host $host; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Scheme $scheme; - proxy_set_header X-Script-Name /searx; - proxy_buffering off; - } - - -Enable ``base_url`` in ``searx/settings.yml`` - -.. code:: yaml - - base_url : http://your.domain.tld/searx/ - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - sudo -H service uwsgi restart - -disable logs -^^^^^^^^^^^^ - -for better privacy you can disable nginx logs about searx. - -how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` -add: - -.. code:: nginx - - access_log /dev/null; - error_log /dev/null; - -Restart service: - -.. code:: sh - - sudo -H service nginx restart - -with apache ------------ - -Add wsgi mod: - -.. code:: sh - - sudo -H apt-get install libapache2-mod-uwsgi - sudo -H a2enmod uwsgi - -Add this configuration in the file ``/etc/apache2/apache2.conf``: - -.. code:: apache - - - Options FollowSymLinks Indexes - SetHandler uwsgi-handler - uWSGISocket /run/uwsgi/app/searx/socket - - -Note that if your instance of searx is not at the root, you should change -```` by the location of your instance, like ````. - -Restart Apache: - -.. code:: sh - - sudo -H /etc/init.d/apache2 restart - -disable logs -~~~~~~~~~~~~ - -For better privacy you can disable Apache logs. - -.. warning:: - - You can only disable logs for the whole (virtual) server not for a specific - path. - -Go back to ``/etc/apache2/apache2.conf`` and above ```` add: - -.. code:: apache - - CustomLog /dev/null combined - -Restart Apache: - -.. code:: sh - - sudo -H /etc/init.d/apache2 restart - -How to update -============= - -.. code:: sh - - cd /usr/local/searx - sudo -H -u searx -i - -.. code:: sh - - (searx)$ . ./searx-ve/bin/activate - (searx)$ git stash - (searx)$ git pull origin master - (searx)$ git stash apply - (searx)$ ./manage.sh update_packages - -.. code:: sh - - sudo -H service uwsgi restart - -Docker -====== - -Make sure you have installed Docker. For instance, you can deploy searx like this: - -.. code:: sh - - docker pull wonderfall/searx - docker run -d --name searx -p $PORT:8888 wonderfall/searx - -Go to ``http://localhost:$PORT``. - -See https://hub.docker.com/r/wonderfall/searx/ for more informations. It's also -possible to build searx from the embedded Dockerfile. - -.. code:: sh - - git clone https://github.com/asciimoo/searx.git - cd searx - docker build -t whatever/searx . - -References -========== - -* https://about.okhin.fr/posts/Searx/ with some additions - -* How to: `Setup searx in a couple of hours with a free SSL certificate - `__ - diff --git a/docs/index.rst b/docs/index.rst index 8fd37cbdc..d9503fef6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +================ Welcome to searx ================ @@ -22,37 +23,10 @@ searx can be used over Tor for online anonymity. Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`. - -User documentation ------------------- - -.. toctree:: - :maxdepth: 1 - - user/search_syntax - user/own-instance - -Administrator documentation ---------------------------- - -.. toctree:: - :maxdepth: 1 - - dev/install/installation - admin/api - admin/filtron - admin/morty - blog/blog - -Developer documentation ------------------------ - .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - dev/quickstart - dev/contribution_guide - dev/engine_overview - dev/search_api - dev/plugins - dev/translation + user/index + admin/index + dev/index + blog/index diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 000000000..b13aca216 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,9 @@ +================== +User documentation +================== + +.. toctree:: + :maxdepth: 1 + + search_syntax + own-instance -- cgit v1.2.3 From 97b86fd184e81263b818dfd2168385c2e60f327a Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 13 Dec 2019 14:57:07 +0100 Subject: doc: document the new reST & gh-pages workflow Signed-off-by: Markus Heiser --- docs/conf.py | 2 ++ docs/dev/contribution_guide.rst | 59 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 58 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 5186d0123..c0bd246ac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,6 +6,7 @@ from pallets_sphinx_themes import ProjectLink GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx") SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me") +DOCS_URL = os.environ.get("DOCS_URL", "https://asciimoo.github.io/searx/") # Project -------------------------------------------------------------- @@ -30,6 +31,7 @@ extlinks['pull'] = ('https://github.com/asciimoo/searx/pull/%s', 'PR ') extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://') extlinks['patch'] = (GIT_URL + '/commit/%s', '#') extlinks['search'] = (SEARX_URL + '/%s', '#') +extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ') extensions = [ 'sphinx.ext.extlinks', diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 9414de2c9..22d690033 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -82,8 +82,61 @@ Translation currently takes place on :ref:`transifex `. Documentation ============= -.. admonition:: ToDo +.. _Sphinx: http://www.sphinx-doc.org +.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html - docs are no longer in gh-branch +.. sidebar:: The reST sources - Update this chapter and document the /docs workflow!! + has been moved from ``gh-branch`` into ``master`` (:origin:`docs`). + +The documentation is built using Sphinx_. So in order to be able to generate +the required files, you have to install it on your system. Much easier, use +Makefile our targets. + +Here is an example which makes complete rebuild: + +.. code:: sh + + $ make docs-clean docs + ... + The HTML pages are in dist/docs. + + +live build +---------- + +Live build is like WYSIWYG, If you want to edit the documentation, its +recommended to use. The Makefile target ``docs-live`` builds the docs, opens URL +in your favorite browser and rebuilds every time a reST file has been changed. + +.. code:: sh + + $ make docs-clean docs-clean + ... + The HTML pages are in dist/docs. + ... Serving on http://0.0.0.0:8080 + ... Start watching changes + + + +deploy on github.io +------------------- + +To deploy documentation at :docs:`github.io <.>` use Makefile target +``gh-pages``, which will builds the documentation, clones searx into a sub +folder ``gh-pages``, cleans it, copies the doc build into and runs all the +needed git add, commit and push: + +.. code:: sh + + $ make gh-pages + ... + SPHINX docs --> file://<...>/dist/docs + The HTML pages are in dist/docs. + ... + Cloning into 'gh-pages' ... + ... + cd gh-pages; git checkout gh-pages >/dev/null + Switched to a new branch 'gh-pages' + ... + doc available at --> https://asciimoo.github.io/searx -- cgit v1.2.3 From e4e578e8a972ff7d7d224c30f2a109d2b5438ea1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 13 Dec 2019 14:58:13 +0100 Subject: doc: theme - make sidebar less eye-catching Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index ae59adead..10f5b4eda 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -13,3 +13,18 @@ a:hover { p.version-warning { background-color: #004b6b; } + +div.sidebar { + background-color: whitesmoke; + border-color: lightsteelblue; + border-radius: 3pt; +} + +p.sidebar-title, .sidebar p { + margin: 6pt; +} + +.sidebar li { + list-style-type: disclosure-closed; +} + -- cgit v1.2.3 From fcd7f4cd1205db48c8796a1ba12bcb1d358a554e Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 13 Dec 2019 15:22:10 +0100 Subject: doc: add note about docs-clean target BTW: fix some typos Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 22d690033..064f28e63 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -93,7 +93,7 @@ The documentation is built using Sphinx_. So in order to be able to generate the required files, you have to install it on your system. Much easier, use Makefile our targets. -Here is an example which makes complete rebuild: +Here is an example which makes a complete rebuild: .. code:: sh @@ -105,13 +105,18 @@ Here is an example which makes complete rebuild: live build ---------- +.. sidebar:: docs-clean + + It is recommended to assert a complete rebuild before deploying (use + ``docs-clean``). + Live build is like WYSIWYG, If you want to edit the documentation, its recommended to use. The Makefile target ``docs-live`` builds the docs, opens URL in your favorite browser and rebuilds every time a reST file has been changed. .. code:: sh - $ make docs-clean docs-clean + $ make docs-live ... The HTML pages are in dist/docs. ... Serving on http://0.0.0.0:8080 @@ -129,7 +134,7 @@ needed git add, commit and push: .. code:: sh - $ make gh-pages + $ make docs-clean gh-pages ... SPHINX docs --> file://<...>/dist/docs The HTML pages are in dist/docs. -- cgit v1.2.3 From f09459b98ae877d7dfd40d85c0edf058c65913d5 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 18 Dec 2019 16:11:05 +0100 Subject: doc: describe Makefile targets With the aim to simplify development cycles, started with PR #1756 a Makefile based boilerplate was added. This patch adds the missing developer documentation. Signed-off-by: Markus Heiser --- docs/conf.py | 1 + docs/dev/contribution_guide.rst | 15 ++- docs/dev/index.rst | 1 + docs/dev/makefile.rst | 217 ++++++++++++++++++++++++++++++++++++++++ docs/dev/quickstart.rst | 26 ++++- 5 files changed, 253 insertions(+), 7 deletions(-) create mode 100644 docs/dev/makefile.rst (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index c0bd246ac..64c7a715f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,6 +32,7 @@ extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://') extlinks['patch'] = (GIT_URL + '/commit/%s', '#') extlinks['search'] = (SEARX_URL + '/%s', '#') extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ') +extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ') extensions = [ 'sphinx.ext.extlinks', diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 064f28e63..6d8d3924d 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -79,6 +79,8 @@ Translation currently takes place on :ref:`transifex `. Please, do not update translation files in the repo. +.. _contrib docs: + Documentation ============= @@ -91,7 +93,7 @@ Documentation The documentation is built using Sphinx_. So in order to be able to generate the required files, you have to install it on your system. Much easier, use -Makefile our targets. +our :ref:`makefile`. Here is an example which makes a complete rebuild: @@ -101,6 +103,7 @@ Here is an example which makes a complete rebuild: ... The HTML pages are in dist/docs. +.. _make docs-live: live build ---------- @@ -110,9 +113,10 @@ live build It is recommended to assert a complete rebuild before deploying (use ``docs-clean``). -Live build is like WYSIWYG, If you want to edit the documentation, its -recommended to use. The Makefile target ``docs-live`` builds the docs, opens URL -in your favorite browser and rebuilds every time a reST file has been changed. +Live build is like WYSIWYG. If you want to edit the documentation, its +recommended to use. The Makefile target ``docs-live`` builds the docs, opens +URL in your favorite browser and rebuilds every time a reST file has been +changed. .. code:: sh @@ -123,12 +127,13 @@ in your favorite browser and rebuilds every time a reST file has been changed. ... Start watching changes +.. _deploy on github.io: deploy on github.io ------------------- To deploy documentation at :docs:`github.io <.>` use Makefile target -``gh-pages``, which will builds the documentation, clones searx into a sub +:ref:`make gh-pages`, which will builds the documentation, clones searx into a sub folder ``gh-pages``, cleans it, copies the doc build into and runs all the needed git add, commit and push: diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 8e18066ca..93340c1db 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -11,3 +11,4 @@ Developer documentation search_api plugins translation + makefile diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst new file mode 100644 index 000000000..65cddd3ee --- /dev/null +++ b/docs/dev/makefile.rst @@ -0,0 +1,217 @@ +.. _makefile: + +================ +Makefile Targets +================ + +.. sidebar:: build environment + + Before looking deeper at the targets, first read about :ref:`makefile setup` + and :ref:`make pyenv`. + +With the aim to simplify development cycles, started with :pull:`1756` a +``Makefile`` based boilerplate was added. + +The usage is simple, just type ``make {target-name}`` to *build* a target. +Calling the ``help`` target gives a first overview:: + + $ make help + test - run developer tests + docs - build documentation + docs-live - autobuild HTML documentation while editing + run - run developer instance + install - developer install (./local) + uninstall - uninstall (./local) + gh-pages - build docs & deploy on gh-pages branch + clean - drop builds and environments + ... + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: entry + + +.. _makefile setup: + +Setup +===== + +.. _git stash: https://git-scm.com/docs/git-stash + +The main setup is done in the :origin:`Makefile`:: + + export GIT_URL=https://github.com/asciimoo/searx + export SEARX_URL=https://searx.me + export DOCS_URL=https://asciimoo.github.io/searx + +.. sidebar:: fork & upstream + + Commit changes in your (local) branch, fork or whatever, but do not push them + upstream / `git stash`_ is your friend. + +:GIT_URL: Changes this, to point to your searx fork. + +:SEARX_URL: Changes this, to point to your searx instance. + +:DOCS_URL: If you host your own (branded) documentation, change this URL. + +.. _make pyenv: + +Python environment +================== + +.. sidebar:: activate environment + + ``source ./local/py3/bin/activate`` + +With Makefile we do no longer need to build up the virualenv manually (as +described in the :ref:`devquickstart` guide). Jump into your git working tree +and release a ``make pyenv``: + +.. code:: sh + + $ cd ~/searx-clone + $ make pyenv + PYENV usage: source ./local/py3/bin/activate + ... + +With target ``pyenv`` a development environment (aka virtualenv) was build up in +``./local/py3/``. To make a *developer install** of searx (:origin:`setup.py`) +into this environment make target ``install`` + +.. code:: sh + + $ make install + PYENV usage: source ./local/py3/bin/activate + PYENV using virtualenv from ./local/py3 + PYENV install . + +You have never to think about intermediate targets like ``pyenv`` or +``install``, the ``Makefile`` chains them as requisites. Just run your main +target. + +.. sidebar:: drop environment + + To get rid of the existing environment before re-build use :ref:`clean target + ` first. + +If you think, something goes wrong with your ./local environment or you change +the :origin:`setup.py` file (or the requirements listed in +:origin:`requirements-dev.txt` and :origin:`requirements.txt`), you have to call +:ref:`make clean`. + + +.. _make run: + +``make run`` +============ + +To get up a running a developer instance simply call ``make run``. This enables +*debug* option in :origin:`searx/settings.yml`, starts ``./searx/webapp.py`` +instance, disables *debug* option and opens the site (xdg-open): + +.. code:: sh + + $ make run + PYENV usage: source ./local/py3/bin/activate + PYENV install . + ./local/py3/bin/python ./searx/webapp.py + ... + INFO:werkzeug: * Running on http://127.0.0.1:8888/ (Press CTRL+C to quit) + ... + +.. _make clean: + +``make clean`` +============== + +Drop all intermediate files, all builds, but keep sources untouched. Includes +target ``pyclean`` which drops ./local environment. Before calling ``make +clean`` stop all processes using :ref:`make pyenv`. + +.. code:: sh + + $ make clean + CLEAN pyclean + CLEAN clean + +.. _make docs: + +``make docs docs-live docs-clean`` +================================== + +We describe the usage of the ``doc*`` targets in the :ref:`How to contribute / +Documentation ` section. If you want to edit the documentation +read our :ref:`make docs-live` section. If you are working in your own brand, +adjust your :ref:`Makefile setup `. + + +.. _make gh-pages: + +``make gh-pages`` +================= + +To deploy on github.io first adjust your :ref:`Makefile setup `. For any further read :ref:`deploy on github.io`. + +.. _make test: + +``make test`` +============= + +Runs a series of tests: ``test.pep8``, ``test.unit``, ``test.robot`` and does +additional :ref:`pylint checks `. You can run tests selective, +e.g.: + +.. code:: sh + + $ make test.pep8 test.unit + . ./local/py3/bin/activate; ./manage.sh pep8_check + [!] Running pep8 check + . ./local/py3/bin/activate; ./manage.sh unit_tests + [!] Running unit tests + +.. _make pylint: + +``make pylint`` +=============== + +.. _Pylint: https://www.pylint.org/ + +Before commiting its recommend to do some (more) linting. Pylint_ is known as +one of the best source-code, bug and quality checker for the Python programming +language. Pylint_ is not yet a quality gate within our searx project (like +:ref:`test.pep8 ` it is), but Pylint_ can help to improve code +quality anyway. The pylint profile we use at searx project is found in +project's root folder :origin:`.pylintrc`. + +Code quality is a ongoing process. Don't try to fix all messages from Pylint, +run Pylint and check if your changed lines are bringing up new messages. If so, +fix it. By this, code quality gets incremental better and if there comes the +day, the linting is balanced out, we might decide to add Pylint as a quality +gate. + + +``make pybuild`` +================ + +.. _PyPi: https://pypi.org/ +.. _twine: https://twine.readthedocs.io/en/latest/ + +Build Python packages in ``./dist/py``. + +.. code:: sh + + $ make pybuild + ... + BUILD pybuild + running sdist + running egg_info + ... + $ ls ./dist/py/ + searx-0.15.0-py3-none-any.whl searx-0.15.0.tar.gz + +To upload packages to PyPi_, there is also a ``upload-pypi`` target. It needs +twine_ to be installed. Since you are not the owner of :pypi:`searx` you will +never need the latter. diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index a4a37a266..e40772b3b 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -4,15 +4,23 @@ Development Quickstart ====================== +.. sidebar:: :ref:`makefile` + + For additional developer purpose there are :ref:`makefile`. + This quickstart guide gets your environment set up with searx. Furthermore, it gives a short introduction to the ``manage.sh`` script. How to setup your development environment ========================================= +.. sidebar:: :ref:`make pyenv ` + + Alternatively use the :ref:`make pyenv`. + First, clone the source code of searx to the desired folder. In this case the source is cloned to ``~/myprojects/searx``. Then create and activate the -searx-ve virtualenv and install the required packages using manage.sh. +searx-ve virtualenv and install the required packages using ``manage.sh``. .. code:: sh @@ -27,6 +35,10 @@ searx-ve virtualenv and install the required packages using manage.sh. How to run tests ================ +.. sidebar:: :ref:`make test.unit ` + + Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets. + Tests can be run using the ``manage.sh`` script. Following tests and checks are available: @@ -41,7 +53,8 @@ For example unit tests are run with the command below: ./manage.sh unit_tests -For further test options, please consult the help of the ``manage.sh`` script. +For further test options, please consult the help of the ``manage.sh`` script or +read :ref:`make test`. How to compile styles and javascript @@ -97,6 +110,11 @@ After installing grunt, the files can be built using the following command: Tips for debugging/development ============================== +.. sidebar:: :ref:`make run` + + Makefile target ``run`` already enables debug option for your developer + session / see :ref:`make run`. + Turn on debug logging Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea to turn on debug logging. When debug logging is enabled a @@ -104,6 +122,10 @@ Turn on debug logging message. It can be turned on by setting ``debug: False`` to ``debug: True`` in :origin:`settings.yml `. +.. sidebar:: :ref:`make test` + + Alternatively use the :ref:`make test` targets. + Run ``./manage.sh tests`` before creating a PR. Failing build on Travis is common because of PEP8 checks. So a new commit must be created containing these format fixes. This phase can be skipped if -- cgit v1.2.3 From 2b4526916dd8092191baa5b9387e8198e5072b83 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 18 Dec 2019 18:32:42 +0100 Subject: edoc: -- makefile.rst fix typo and add extlinks['man'] Signed-off-by: Markus Heiser --- docs/conf.py | 1 + docs/dev/makefile.rst | 12 ++++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 64c7a715f..9eba67cf6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,7 @@ extlinks['patch'] = (GIT_URL + '/commit/%s', '#') extlinks['search'] = (SEARX_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', '') extensions = [ 'sphinx.ext.extlinks', diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 65cddd3ee..00825623c 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -4,13 +4,16 @@ Makefile Targets ================ +.. _gnu-make: https://www.gnu.org/software/make/manual/make.html#Introduction + .. sidebar:: build environment Before looking deeper at the targets, first read about :ref:`makefile setup` and :ref:`make pyenv`. With the aim to simplify development cycles, started with :pull:`1756` a -``Makefile`` based boilerplate was added. +``Makefile`` based boilerplate was added. If you are not familiar with +Makefiles, we recommend to read gnu-make_ introduction. The usage is simple, just type ``make {target-name}`` to *build* a target. Calling the ``help`` target gives a first overview:: @@ -77,7 +80,7 @@ and release a ``make pyenv``: ... With target ``pyenv`` a development environment (aka virtualenv) was build up in -``./local/py3/``. To make a *developer install** of searx (:origin:`setup.py`) +``./local/py3/``. To make a *developer install* of searx (:origin:`setup.py`) into this environment make target ``install`` .. code:: sh @@ -108,8 +111,9 @@ the :origin:`setup.py` file (or the requirements listed in ============ To get up a running a developer instance simply call ``make run``. This enables -*debug* option in :origin:`searx/settings.yml`, starts ``./searx/webapp.py`` -instance, disables *debug* option and opens the site (xdg-open): +*debug* option in :origin:`searx/settings.yml`, starts a ``./searx/webapp.py`` +instance, disables *debug* option again and opens the URL in your favorite WEB +browser (:man:`xdg-open`): .. code:: sh -- cgit v1.2.3 From bee19a76f7dc8b86af3ef342acd3f4db72f51543 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 19 Dec 2019 17:05:50 +0100 Subject: doc: add reST primer (inital / WIP) preview: https://return42.github.io/searx/dev/reST.html includes: - :class: rst-example // admonitions with (rendered) reST markup example - extlinks to docutils Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 42 +++ docs/conf.py | 11 +- docs/dev/index.rst | 1 + docs/dev/makefile.rst | 2 +- docs/dev/reST.rst | 491 ++++++++++++++++++++++++++++++++++++ 5 files changed, 544 insertions(+), 3 deletions(-) create mode 100644 docs/dev/reST.rst (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 10f5b4eda..ee084d499 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -28,3 +28,45 @@ p.sidebar-title, .sidebar p { list-style-type: disclosure-closed; } + +/* admonitions with (rendered) reST markup examples (:class: rst-example) + * + * .. admonition:: title of the example + * :class: rst-example + * .... +/* navigation menu: use sans font and select light/dark colors for better +* contrast. +*/ + +div.rst-example { + padding-left: 12px; + padding-right: 12px; + background-color: white; + transform: scale(0.9); + transition: transform 1s; +} + +/* div.rst-example > .admonition-title { */ +/* background-color: inherit; */ +/* color: inherit; */ +/* } */ + +/* div.rst-example > .admonition-title:after{ */ +/* font-family: inherit; */ +/* font-style: italic; */ +/* content: " // hover mouse over .."; */ +/* } */ + +@media screen { + div.rst-example:hover { + transform: scale(1); + background-color: inherit; + padding-left: inherit; + padding-right: inherit; + border-left: inherit; + } + + div.rst-example:hover > .admonition-title { + display: none; + } +} diff --git a/docs/conf.py b/docs/conf.py index 9eba67cf6..33954cbd2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,6 +14,7 @@ project = u'searx' copyright = u'2015-2019, Adam Tauber, Noémi Ványi' author = u'Adam Tauber' release, version = VERSION_STRING, VERSION_STRING +highlight_language = 'none' # General -------------------------------------------------------------- @@ -34,6 +35,12 @@ extlinks['search'] = (SEARX_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', '') +extlinks['duref'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') +extlinks['durole'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '') +extlinks['dudir'] = ( + 'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '') extensions = [ 'sphinx.ext.extlinks', @@ -46,9 +53,9 @@ extensions = [ intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), - # "flask": ("https://flask.palletsprojects.com/", None), + "flask": ("https://flask.palletsprojects.com/", None), # "werkzeug": ("https://werkzeug.palletsprojects.com/", None), - # "jinja": ("https://jinja.palletsprojects.com/", None), + "jinja": ("https://jinja.palletsprojects.com/", None), } issues_github_path = "asciimoo/searx" diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 93340c1db..cb913a82b 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -12,3 +12,4 @@ Developer documentation plugins translation makefile + reST diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 00825623c..f5957001c 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -81,7 +81,7 @@ and release a ``make pyenv``: With target ``pyenv`` a development environment (aka virtualenv) was build up in ``./local/py3/``. To make a *developer install* of searx (:origin:`setup.py`) -into this environment make target ``install`` +into this environment, use make target ``install``: .. code:: sh diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst new file mode 100644 index 000000000..c8482e77d --- /dev/null +++ b/docs/dev/reST.rst @@ -0,0 +1,491 @@ +.. _reST primer: + +=========== +reST primer +=========== + +.. sidebar:: KISS_ and readability_ + + Instead of defining more and more roles, we at searx encourage our + contributors to follow principles like KISS_ and readability_. + +We at searx are using reStructuredText (aka reST_) markup for all kind of +documentation, with the builders from the Sphinx_ project a HTML output is +generated and deployed at :docs:`github.io <.>`. + +The sources of Searx's documentation are located at :origin:`docs`. Run +:ref:`make docs-live ` to build HTML while editing. + +------ + +.. contents:: Contents + :depth: 3 + :local: + :backlinks: entry + +Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is +used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_. + +.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html + +.. sidebar:: Content matters + + The readability_ of the reST sources has its value, therefore we recommend to + make sparse usage of reST markup / .. content matters! + +**reST** is a plaintext markup language, its markup is *mostly* intuitive and +you will not need to learn much to produce well formed articles with. I use the +word *mostly*: like everything in live, reST has its advantages and +disadvantages, some markups feel a bit grumpy (especially if you are used to +other plaintext markups). + +Soft skills +=========== + +Before going any deeper into the markup let's face on some **soft skills** a +trained author brings with, to reach a well feedback from readers: + +- Documentation is dedicated to an audience and answers questions from the + audience point of view. +- Don't detail things which are general knowledge from the audience point of + view. +- Limit the subject, use cross links for any further reading. + +To be more concrete what a *point of view* means. In the (:origin:`docs`) +folder we have three sections (and the *blog* folder), each dedicate to a +different group of audience. + +.. sidebar:: Further reading + + - Sphinx-Primer_ + - `Sphinx markup constructs`_ + - reST_, docutils_, `docutils FAQ`_ + - Sphinx_, `sphinx-doc FAQ`_ + - `sphinx config`_, doctree_ + - `sphinx cross references`_ + - intersphinx_ + - `Sphinx's autodoc`_ + - `Sphinx's Python domain`_, `Sphinx's C domain`_ + +User's POV: :origin:`docs/user` + A typical user knows about search engines and might have heard about + meta crawlers and privacy. + +Admin's POV: :origin:`docs/admin` + A typical Admin knows about setting up services on a linux system, but he does + not know all the pros and cons of a searx setup. + +Developer's POV: :origin:`docs/dev` + Depending on the readability_ of code, a typical developer is able to read and + understand source code. Describe what a item aims to do (e.g. a function), + describe chronological order matters, describe it. Name the *out-of-limits + condition* and all the side effects a external developer will not know. + +.. _reST inline markup: + +Basic inline markup +=================== + +``*italics*`` -- *italics* + one asterisk for emphasis + +``**boldface**`` -- **boldface** + two asterisks for strong emphasis and + +````foo()```` -- ``foo()`` + backquotes for code samples and literals. + +``\*foo is a pointer`` -- \*foo is a pointer + If asterisks or backquotes appear in running text and could be confused with + inline markup delimiters, they have to be escaped with a backslash (``\*foo is + a pointer``). + + +Roles +===== + +A *custom interpreted text role* (:duref:`ref `) is an inline piece of +explicit markup. It signifies that that the enclosed text should be interpreted +in a specific way. The general syntax is ``:rolename:`content```. + +Docutils supports the following roles: + +* :durole:`emphasis` -- equivalent of ``*emphasis*`` +* :durole:`strong` -- equivalent of ``**strong**`` +* :durole:`literal` -- equivalent of ````literal```` +* :durole:`subscript` -- subscript text +* :durole:`superscript` -- superscript text +* :durole:`title-reference` -- for titles of books, periodicals, and other + materials + +Refer to `Sphinx Roles`_ for roles added by Sphinx. + + +Anchors & Links +=============== + +.. _reST anchor: + +Anchors +------- + +.. _ref role: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref + +To refer a point in the documentation a anchor is needed. The :ref:`reST +template ` shows an example where a chapter titled *"Chapters"* +gets an anchor named ``chapter title``. Another example from *this* document, +where the anchor named ``reST anchor``: + +.. code:: reST + + .. _reST anchor: + + Anchors + ------- + + To refer a point in the documentation a anchor is needed ... + +To refer anchors use the `ref role`_ markup: + +.. code:: reST + + Visit chapter :ref:`reST anchor`. + Or set hyperlink text manualy :ref:`foo bar `. + +.. admonition:: ``:ref:`` role + :class: rst-example + + Visist chapter :ref:`reST anchor` + Or set hyperlink text manualy :ref:`foo bar `. + +.. _reST ordinary ref: + +link ordinary URL +----------------- + +If you need to reference external URLs use *named* hyperlinks to maintain +readability of reST sources. Here is a example taken from *this* article: + +.. code:: reST + + .. _Sphinx Field Lists: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html + + With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more + readable. + + And this shows the alternative (less readable) hyperlink markup `Sphinx Field + Lists + `__. + +.. admonition:: Named hyperlink + :class: rst-example + + With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more + readable. + + And this shows the alternative (less readable) hyperlink markup `Sphinx Field + Lists + `__. + + +.. _reST smart ref: + +smart references +---------------- + +With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external +content becomes smart. To refer ... + +sphinx.ext.extlinks_: + +:project's wiki article: :wiki:`Searx-instances` +:to docs public URL: :docs:`dev/reST.html` +:files & folders from origin: :origin:`docs/dev/reST.rst` +:a pull request: :pull:`1756` +:a patch: :patch:`af2cae6` +:a PyPi package: :pypi:`searx` +:a manual page man: :man:`bash` + +.. code:: reST + + :project's wiki article: :wiki:`Searx-instances` + :to docs public URL: :docs:`dev/reST.html` + :files & folders from origin: :origin:`docs/dev/reST.rst` + :a pull request: :pull:`1756` + :a patch: :patch:`af2cae6` + :a PyPi package: :pypi:`searx` + :a manual page man: :man:`bash` + + +intersphinx_: + + :external anchor: :ref:`python:and` + :external doc anchor: :doc:`jinja:templates` + :python code object: :py:obj:`datetime.datetime` + :flask code object: webapp is a :py:obj:`flask.Flask` app + +.. code:: reST + + :external anchor: :ref:`python:and` + :external doc anchor: :doc:`jinja:templates` + :python code object: :py:obj:`datetime.datetime` + :flask code object: webapp is a :py:obj:`flask.Flask` app + + +Intersphinx is configured in :origin:`docs/conf.py`: + +.. code:: python + + intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "flask": ("https://flask.palletsprojects.com/", None), + "jinja": ("https://jinja.palletsprojects.com/", None), + } + + +To list all anchors of the inventory (e.g. ``python``) use: + +.. code:: sh + + $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv + + +.. _reST basic structure: + +Basic article structure +======================= + +The basic structure of an article makes use of heading adornments to markup +chapter, sections and subsections. + +#. ``=`` with overline for document title +#. ``=`` for chapters +#. ``-`` for sections +#. ``~`` for subsections + +.. _reST template: + +.. admonition:: reST template + :class: rst-example + + .. code:: reST + + .. _document title: + + ============== + Document title + ============== + + Lorem ipsum dolor sit amet, consectetur adipisici elit .. + Further read :ref:`chapter title`. + + .. _chapter title: + + Chapters + ======== + + Ut enim ad minim veniam, quis nostrud exercitation ullamco + laboris nisi ut aliquid ex ea commodi consequat ... + + Section + ------- + + lorem .. + + Subsection + ~~~~~~~~~~ + + lorem .. + +.. _reST lists: + +List markups +============ + +Bullet list +----------- + +List markup (:duref:`ref `) is simple: + +.. code:: reST + + - This is a bulleted list. + + 1. Nested lists are possible, but be aware that they must be separated from + the parent list items by blank line + 2. Second item of nested list + + - It has two items, the second + item uses two lines. + + #. This is a numbered list. + #. It has two items too. + +.. admonition:: bullet list + :class: rst-example + + - This is a bulleted list. + + 1. Nested lists are possible, but be aware that they must be separated from + the parent list items by blank line + 2. Second item of nested list + + - It has two items, the second + item uses two lines. + + #. This is a numbered list. + #. It has two items too. + + +Definition list +--------------- + +.. sidebar:: definition term + + Note that the term cannot have more than one line of text. + +Definition lists (:duref:`ref `) are created as follows: + +.. code:: reST + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + +.. admonition:: definition list + :class: rst-example + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + + +Quoted paragraphs +----------------- + +Quoted paragraphs (:duref:`ref `) are created by just indenting +them more than the surrounding paragraphs. Line blocks (:duref:`ref +`) are a way of preserving line breaks: + +.. code:: reST + + normal paragraph ... + lorem ipsum. + + Quoted paragraph ... + lorem ipsum. + + | These lines are + | broken exactly like in + | the source file. + + +.. admonition:: Quoted paragraph and line block + :class: rst-example + + normal paragraph ... + lorem ipsum. + + Quoted paragraph ... + lorem ipsum. + + | These lines are + | broken exactly like in + | the source file. + + +.. _reST field list: + +Field Lists +----------- + +.. _Sphinx Field Lists: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html + +.. sidebar:: bibliographic fields + + First lines fields are bibliographic fields, see `Sphinx Field Lists`_. + +Field lists are used as part of an extension syntax, such as options for +directives, or database-like records meant for further processing. Field lists +are mappings from field names to field bodies. They marked up like this: + +.. code:: reST + + :fieldname: Field content + :foo: first paragraph in field foo + + second paragraph in field foo + + :bar: Field content + +.. admonition:: Field List + :class: rst-example + + :fieldname: Field content + :foo: first paragraph in field foo + + second paragraph in field foo + + :bar: Field content + + +They are commonly used in Python documentation: + +.. code:: python + + def my_function(my_arg, my_other_arg): + """A function just for me. + + :param my_arg: The first of my arguments. + :param my_other_arg: The second of my arguments. + + :returns: A message (just for me, of course). + """ + +Further list blocks +------------------- + +- field lists (:duref:`ref `, with caveats noted in + :ref:`reST field list`) +- option lists (:duref:`ref `) +- quoted literal blocks (:duref:`ref `) +- doctest blocks (:duref:`ref `) + + +.. _KISS: https://en.wikipedia.org/wiki/KISS_principle +.. _readability: https://docs.python-guide.org/writing/style/ +.. _Sphinx-Primer: + http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _reST: https://docutils.sourceforge.io/rst.html +.. _Sphinx Roles: + https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html +.. _Sphinx: http://www.sphinx-doc.org +.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html +.. _Sphinx markup constructs: + http://www.sphinx-doc.org/en/stable/markup/index.html +.. _`sphinx cross references`: + http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations +.. _sphinx.ext.extlinks: + https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html +.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html +.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html +.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html +.. _Sphinx's Python domain: + http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain +.. _Sphinx's C domain: + http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs +.. _doctree: + http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases +.. _docutils: http://docutils.sourceforge.net/docs/index.html +.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html -- cgit v1.2.3 From e1566e68aa9e18e60a86d0eea8772a3673cb3c7b Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 19 Dec 2019 23:36:53 +0100 Subject: doc: add content to reST primer (WIP) // linuxdoc Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 8 + docs/conf.py | 11 ++ docs/dev/hello.dot | 3 + docs/dev/reST.rst | 313 +++++++++++++++++++++++++----------- docs/dev/svg_image.svg | 10 ++ 5 files changed, 254 insertions(+), 91 deletions(-) create mode 100644 docs/dev/hello.dot create mode 100644 docs/dev/svg_image.svg (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index ee084d499..747cb0507 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -29,6 +29,14 @@ p.sidebar-title, .sidebar p { } +div.admonition, +div.topic { + background-color: #fafafa; + margin: 8px 0px; + padding: 1em; + border: none; +} + /* admonitions with (rendered) reST markup examples (:class: rst-example) * * .. admonition:: title of the example diff --git a/docs/conf.py b/docs/conf.py index 33954cbd2..b960621d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,6 +20,7 @@ highlight_language = 'none' master_doc = "index" source_suffix = '.rst' +numfig = True # usage:: lorem :patch:`f373169` ipsum extlinks = {} @@ -35,6 +36,8 @@ extlinks['search'] = (SEARX_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', '') +#extlinks['role'] = ( +# 'https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-%s', '') extlinks['duref'] = ( 'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') extlinks['durole'] = ( @@ -49,6 +52,12 @@ extensions = [ "sphinx.ext.intersphinx", "pallets_sphinx_themes", "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst + 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. + 'linuxdoc.rstKernelDoc', # Implementation of the 'kernel-doc' reST-directive. + 'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive. + 'linuxdoc.manKernelDoc', # Implementation of the 'kernel-doc-man' builder + 'linuxdoc.cdomain', # Replacement for the sphinx c-domain. + 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling. ] intersphinx_mapping = { @@ -56,6 +65,8 @@ intersphinx_mapping = { "flask": ("https://flask.palletsprojects.com/", None), # "werkzeug": ("https://werkzeug.palletsprojects.com/", None), "jinja": ("https://jinja.palletsprojects.com/", None), + "linuxdoc" : ("https://return42.github.io/linuxdoc/", None), + "sphinx" : ("https://www.sphinx-doc.org/en/master/", None), } issues_github_path = "asciimoo/searx" diff --git a/docs/dev/hello.dot b/docs/dev/hello.dot new file mode 100644 index 000000000..504621dfc --- /dev/null +++ b/docs/dev/hello.dot @@ -0,0 +1,3 @@ +graph G { + Hello -- World +} diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index c8482e77d..5522f9e15 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -18,11 +18,26 @@ The sources of Searx's documentation are located at :origin:`docs`. Run ------ +.. sidebar:: Further reading + + - Sphinx-Primer_ + - `Sphinx markup constructs`_ + - reST_, docutils_, `docutils FAQ`_ + - Sphinx_, `sphinx-doc FAQ`_ + - `sphinx config`_, doctree_ + - `sphinx cross references`_ + - linuxdoc_ + - intersphinx_ + - `Sphinx's autodoc`_ + - `Sphinx's Python domain`_, `Sphinx's C domain`_ + .. contents:: Contents :depth: 3 :local: :backlinks: entry +------ + Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_. @@ -55,18 +70,6 @@ To be more concrete what a *point of view* means. In the (:origin:`docs`) folder we have three sections (and the *blog* folder), each dedicate to a different group of audience. -.. sidebar:: Further reading - - - Sphinx-Primer_ - - `Sphinx markup constructs`_ - - reST_, docutils_, `docutils FAQ`_ - - Sphinx_, `sphinx-doc FAQ`_ - - `sphinx config`_, doctree_ - - `sphinx cross references`_ - - intersphinx_ - - `Sphinx's autodoc`_ - - `Sphinx's Python domain`_, `Sphinx's C domain`_ - User's POV: :origin:`docs/user` A typical user knows about search engines and might have heard about meta crawlers and privacy. @@ -100,25 +103,52 @@ Basic inline markup inline markup delimiters, they have to be escaped with a backslash (``\*foo is a pointer``). +.. _reST basic structure: -Roles -===== +Basic article structure +======================= -A *custom interpreted text role* (:duref:`ref `) is an inline piece of -explicit markup. It signifies that that the enclosed text should be interpreted -in a specific way. The general syntax is ``:rolename:`content```. +The basic structure of an article makes use of heading adornments to markup +chapter, sections and subsections. + +#. ``=`` with overline for document title +#. ``=`` for chapters +#. ``-`` for sections +#. ``~`` for subsections + +.. _reST template: + +.. admonition:: reST template + :class: rst-example -Docutils supports the following roles: + .. code:: reST -* :durole:`emphasis` -- equivalent of ``*emphasis*`` -* :durole:`strong` -- equivalent of ``**strong**`` -* :durole:`literal` -- equivalent of ````literal```` -* :durole:`subscript` -- subscript text -* :durole:`superscript` -- superscript text -* :durole:`title-reference` -- for titles of books, periodicals, and other - materials + .. _document title: -Refer to `Sphinx Roles`_ for roles added by Sphinx. + ============== + Document title + ============== + + Lorem ipsum dolor sit amet, consectetur adipisici elit .. + Further read :ref:`chapter title`. + + .. _chapter title: + + Chapters + ======== + + Ut enim ad minim veniam, quis nostrud exercitation ullamco + laboris nisi ut aliquid ex ea commodi consequat ... + + Section + ------- + + lorem .. + + Subsection + ~~~~~~~~~~ + + lorem .. Anchors & Links @@ -196,42 +226,29 @@ smart references ---------------- With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external -content becomes smart. To refer ... - -sphinx.ext.extlinks_: - -:project's wiki article: :wiki:`Searx-instances` -:to docs public URL: :docs:`dev/reST.html` -:files & folders from origin: :origin:`docs/dev/reST.rst` -:a pull request: :pull:`1756` -:a patch: :patch:`af2cae6` -:a PyPi package: :pypi:`searx` -:a manual page man: :man:`bash` - -.. code:: reST - - :project's wiki article: :wiki:`Searx-instances` - :to docs public URL: :docs:`dev/reST.html` - :files & folders from origin: :origin:`docs/dev/reST.rst` - :a pull request: :pull:`1756` - :a patch: :patch:`af2cae6` - :a PyPi package: :pypi:`searx` - :a manual page man: :man:`bash` - - -intersphinx_: - - :external anchor: :ref:`python:and` - :external doc anchor: :doc:`jinja:templates` - :python code object: :py:obj:`datetime.datetime` - :flask code object: webapp is a :py:obj:`flask.Flask` app - -.. code:: reST - - :external anchor: :ref:`python:and` - :external doc anchor: :doc:`jinja:templates` - :python code object: :py:obj:`datetime.datetime` - :flask code object: webapp is a :py:obj:`flask.Flask` app +content becomes smart. + +========================== ================================== ==================================== +refer ... rendered example markup +========================== ================================== ==================================== +:rst:role:`rfc` :rfc:`822` ``:rfc:`822``` +:rst:role:`pep` :pep:`8` ``:pep:`8``` +sphinx.ext.extlinks_ +-------------------------------------------------------------------------------------------------- +project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances``` +to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html``` +files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst``` +pull request :pull:`1756` ``:pull:`1756``` +patch :patch:`af2cae6` ``:patch:`af2cae6``` +PyPi package :pypi:`searx` ``:pypi:`searx``` +manual page man :man:`bash` ``:man:`bash``` +intersphinx_ +-------------------------------------------------------------------------------------------------- +external anchor :ref:`python:and` ``:ref:`python:and``` +external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates``` +python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime``` +flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask``` +========================== ================================== ==================================== Intersphinx is configured in :origin:`docs/conf.py`: @@ -242,6 +259,8 @@ Intersphinx is configured in :origin:`docs/conf.py`: "python": ("https://docs.python.org/3/", None), "flask": ("https://flask.palletsprojects.com/", None), "jinja": ("https://jinja.palletsprojects.com/", None), + "linuxdoc" : ("https://return42.github.io/linuxdoc/", None), + "sphinx" : ("https://www.sphinx-doc.org/en/master/", None), } @@ -252,52 +271,163 @@ To list all anchors of the inventory (e.g. ``python``) use: $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv -.. _reST basic structure: +Roles +===== -Basic article structure -======================= +A *custom interpreted text role* (:duref:`ref `) is an inline piece of +explicit markup. It signifies that that the enclosed text should be interpreted +in a specific way. The general syntax is ``:rolename:`content```. -The basic structure of an article makes use of heading adornments to markup -chapter, sections and subsections. +========================== ================================== ==================================== +role rendered example markup +========================== ================================== ==================================== +:rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel``` +:rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f``` +:rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File``` +:rst:role:`download` :download:`this file ` ``:download:`this file ``` +:rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2``` +:rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example``` +:rst:role:`command` :command:`ls -la` ``:command:`ls -la``` +:durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic``` +:durole:`strong` :strong:`bold` ``:strong:`bold``` +:durole:`literal` :literal:`foo()` ``:literal:`foo()``` +:durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O`` +:durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2``` +:durole:`title-reference` :title:`Time` ``:title:`Time``` +========================== ================================== ==================================== -#. ``=`` with overline for document title -#. ``=`` for chapters -#. ``-`` for sections -#. ``~`` for subsections +Refer to `Sphinx Roles`_ for roles added by Sphinx. -.. _reST template: -.. admonition:: reST template +Figures & Images +================ + +Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means; +scalable in sense of the build process. Normally in absence of a converter +tool, the build process will break. From the authors POV it’s annoying to care +about the build process when handling with images, especially since he has no +access to the build process. With :ref:`linuxdoc:kfigure` the build process +continues and scales output quality in dependence of installed image processors. + +If you want to add an image, you should use the ``kernel-figure`` and +``kernel-image`` directives. E.g. to insert a figure with a scalable image +format use SVG (:ref:`svg_image_example`): + +.. code:: reST + + .. _svg image example: + + .. kernel-figure:: svg_image.svg + :alt: simple SVG image + + SVG image example + +.. _svg image example: + +.. kernel-figure:: svg_image.svg + :alt: simple SVG image + + SVG image example + +DOT files (aka Graphviz) +------------------------ + +The kernel figure (and image) directive support **DOT** formated files, see + +* DOT: http://graphviz.org/pdf/dotguide.pdf +* Graphviz: http://www.graphviz.org/content/dot-language + +A simple example (:ref:`hello_dot_file`): + +.. code:: reST + + .. kernel-figure:: hello.dot + :alt: hello world + + DOT's hello world example + +.. admonition:: hello.dot :class: rst-example - .. code:: reST + .. kernel-figure:: hello.dot + :alt: hello world - .. _document title: + DOT's hello world example - ============== - Document title - ============== +``kernel-render`` DOT +--------------------- - Lorem ipsum dolor sit amet, consectetur adipisici elit .. - Further read :ref:`chapter title`. +Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the +``kernel-render`` directives. - .. _chapter title: +.. code:: reST - Chapters - ======== + .. kernel-render:: DOT markup + :alt: foobar digraph + :caption: Embedded **DOT** (Graphviz) code - Ut enim ad minim veniam, quis nostrud exercitation ullamco - laboris nisi ut aliquid ex ea commodi consequat ... + digraph foo { + "bar" -> "baz"; + } - Section - ------- +How this will be rendered depends on the installed tools. If Graphviz is +installed, you will see an vector image. If not the raw markup is inserted as +*literal-block* (:ref:`hello_dot_render`). - lorem .. +.. admonition:: DOT markup + :class: rst-example - Subsection - ~~~~~~~~~~ + .. _hello_dot_render: + + .. kernel-render:: DOT + :alt: foobar digraph + :caption: Embedded **DOT** (Graphviz) code + + digraph foo { + "bar" -> "baz"; + } + +The *render* directive has all the options known from the *figure* directive, +plus option ``caption``. If ``caption`` has a value, a *figure* node is +inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if +you want to refer it (:ref:`hello_svg_render`). + + +``kernel-render`` SVG +--------------------- + +.. code:: reST + + .. kernel-render:: SVG markup + :caption: Embedded **SVG** markup + :alt: so-nw-arrow +.. + + .. code:: xml + + + + + + + +.. admonition:: SVG markup + :class: rst-example + + .. _hello_svg_render: + + .. kernel-render:: SVG + :caption: Embedded **SVG** markup + :alt: so-nw-arrow + + + + + + - lorem .. .. _reST lists: @@ -489,3 +619,4 @@ Further list blocks http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases .. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html +.. _linuxdoc: https://return42.github.io/linuxdoc diff --git a/docs/dev/svg_image.svg b/docs/dev/svg_image.svg new file mode 100644 index 000000000..5405f85b8 --- /dev/null +++ b/docs/dev/svg_image.svg @@ -0,0 +1,10 @@ + + + + + + + + -- cgit v1.2.3 From b82f61f7044665b900b0d8f556cbe207f3133837 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 20 Dec 2019 11:01:41 +0100 Subject: doc: reST primer -- describe admonitions & customize their CSS Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 75 +++++++++++++++++++++---------------- docs/dev/reST.rst | 72 +++++++++++++++++++++++++++++++++-- 2 files changed, 111 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 747cb0507..10cfc413e 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -28,53 +28,64 @@ p.sidebar-title, .sidebar p { list-style-type: disclosure-closed; } +/* admonitions +*/ -div.admonition, -div.topic { +div.admonition, div.topic { background-color: #fafafa; margin: 8px 0px; padding: 1em; - border: none; + border-radius: 3pt 0 0 3pt; + border-top: none; + border-right: none; + border-bottom: none; + border-left: 5pt solid #ccc; +} + +p.admonition-title:after { + content: none; +} + +.admonition.hint { border-color: #416dc0b0; } +.admonition.note { border-color: #6c856cb0; } +.admonition.tip { border-color: #85c5c2b0; } +.admonition.attention { border-color: #ecec97b0; } +.admonition.caution { border-color: #a6c677b0; } +.admonition.danger { border-color: #d46262b0; } +.admonition.important { border-color: #dfa3a3b0; } +.admonition.error { border-color: red; } +.admonition.warning { border-color: darkred; } + +.admonition.admonition-generic-admonition-title { + border-color: #416dc0b0; } + /* admonitions with (rendered) reST markup examples (:class: rst-example) * * .. admonition:: title of the example * :class: rst-example * .... -/* navigation menu: use sans font and select light/dark colors for better -* contrast. */ div.rst-example { - padding-left: 12px; - padding-right: 12px; - background-color: white; - transform: scale(0.9); - transition: transform 1s; + padding-left: 12px; + padding-right: 12px; + background-color: inherit; + transform: scale(0.9); + transition: transform 1s; + border-left: none; } -/* div.rst-example > .admonition-title { */ -/* background-color: inherit; */ -/* color: inherit; */ -/* } */ - -/* div.rst-example > .admonition-title:after{ */ -/* font-family: inherit; */ -/* font-style: italic; */ -/* content: " // hover mouse over .."; */ -/* } */ - @media screen { - div.rst-example:hover { - transform: scale(1); - background-color: inherit; - padding-left: inherit; - padding-right: inherit; - border-left: inherit; - } - - div.rst-example:hover > .admonition-title { - display: none; - } + div.rst-example:hover { + transform: scale(1); + padding-left: inherit; + padding-right: inherit; + border-left: inherit; + } + + div.rst-example:hover > .admonition-title { + display: none; + } } diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 5522f9e15..69e4a9305 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -16,8 +16,6 @@ generated and deployed at :docs:`github.io <.>`. The sources of Searx's documentation are located at :origin:`docs`. Run :ref:`make docs-live ` to build HTML while editing. ------- - .. sidebar:: Further reading - Sphinx-Primer_ @@ -36,8 +34,6 @@ The sources of Searx's documentation are located at :origin:`docs`. Run :local: :backlinks: entry ------- - Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_. @@ -593,6 +589,74 @@ Further list blocks - doctest blocks (:duref:`ref `) +Admonitions +=========== + +Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, +:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, , +:dudir:`warning` and the generic :dudir:`admonition `. + +.. code:: reST + + .. admonition:: generic admonition title + + lorem ipsum .. + + .. hint:: + + lorem ipsum .. + + .. note:: + + lorem ipsum .. + + .. warning:: + + lorem ipsum .. + + +.. admonition:: generic admonition title + + lorem ipsum .. + +.. hint:: + + lorem ipsum .. + +.. note:: + + lorem ipsum .. + +.. tip:: + + lorem ipsum .. + +.. attention:: + + lorem ipsum .. + +.. caution:: + + lorem ipsum .. + +.. danger:: + + lorem ipsum .. + +.. important:: + + lorem ipsum .. + +.. error:: + + lorem ipsum .. + +.. warning:: + + lorem ipsum .. + + + .. _KISS: https://en.wikipedia.org/wiki/KISS_principle .. _readability: https://docs.python-guide.org/writing/style/ .. _Sphinx-Primer: -- cgit v1.2.3 From ae7cb5937e597dd59b652333f5e3693efef3c1aa Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 20 Dec 2019 12:10:43 +0100 Subject: docs: reST-primer first proofreading (WIP) Signed-off-by: Markus Heiser --- docs/dev/reST.rst | 138 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 93 insertions(+), 45 deletions(-) (limited to 'docs') diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 69e4a9305..8bab5e332 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -28,6 +28,9 @@ The sources of Searx's documentation are located at :origin:`docs`. Run - intersphinx_ - `Sphinx's autodoc`_ - `Sphinx's Python domain`_, `Sphinx's C domain`_ + - SVG_, ImageMagick_ + - DOT_, `Graphviz's dot`_, Graphviz_ + .. contents:: Contents :depth: 3 @@ -76,9 +79,9 @@ Admin's POV: :origin:`docs/admin` Developer's POV: :origin:`docs/dev` Depending on the readability_ of code, a typical developer is able to read and - understand source code. Describe what a item aims to do (e.g. a function), - describe chronological order matters, describe it. Name the *out-of-limits - condition* and all the side effects a external developer will not know. + understand source code. Describe what a item aims to do (e.g. a function). + If the chronological order matters, describe it. Name the *out-of-limits + conditions* and all the side effects a external developer will not know. .. _reST inline markup: @@ -254,7 +257,7 @@ Intersphinx is configured in :origin:`docs/conf.py`: intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "flask": ("https://flask.palletsprojects.com/", None), - "jinja": ("https://jinja.palletsprojects.com/", None), + "jinja": ("https://jinja.palletsprojects.com/", None), "linuxdoc" : ("https://return42.github.io/linuxdoc/", None), "sphinx" : ("https://www.sphinx-doc.org/en/master/", None), } @@ -298,6 +301,12 @@ Refer to `Sphinx Roles`_ for roles added by Sphinx. Figures & Images ================ +.. sidebar:: Image processing + + With the directives from :ref:`linuxdoc ` the build process + is flexible. To get best results in the generated output format, install + ImageMagick_ and Graphviz_. + Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means; scalable in sense of the build process. Normally in absence of a converter tool, the build process will break. From the authors POV it’s annoying to care @@ -307,36 +316,44 @@ continues and scales output quality in dependence of installed image processors. If you want to add an image, you should use the ``kernel-figure`` and ``kernel-image`` directives. E.g. to insert a figure with a scalable image -format use SVG (:ref:`svg_image_example`): +format use SVG (:ref:`svg image example`): .. code:: reST .. _svg image example: .. kernel-figure:: svg_image.svg - :alt: simple SVG image + :alt: SVG image example - SVG image example + simple SVG image + + To refer the figure, a caption block is needed: :ref:`svg image example`. .. _svg image example: .. kernel-figure:: svg_image.svg - :alt: simple SVG image + :alt: SVG image example + + simple SVG image - SVG image example +To refer the figure, a caption block is needed: :ref:`svg image example`. DOT files (aka Graphviz) ------------------------ -The kernel figure (and image) directive support **DOT** formated files, see +With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is +given. -* DOT: http://graphviz.org/pdf/dotguide.pdf -* Graphviz: http://www.graphviz.org/content/dot-language +- `Graphviz's dot`_ +- DOT_ +- Graphviz_ -A simple example (:ref:`hello_dot_file`): +A simple example is shown in :ref:`dot file example`: .. code:: reST + .. _dot file example: + .. kernel-figure:: hello.dot :alt: hello world @@ -345,6 +362,8 @@ A simple example (:ref:`hello_dot_file`): .. admonition:: hello.dot :class: rst-example + .. _dot file example: + .. kernel-figure:: hello.dot :alt: hello world @@ -354,77 +373,100 @@ A simple example (:ref:`hello_dot_file`): --------------------- Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the -``kernel-render`` directives. +:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is +shown in figure :ref:`dot render example`: -.. code:: reST +.. code-block:: rst - .. kernel-render:: DOT markup - :alt: foobar digraph - :caption: Embedded **DOT** (Graphviz) code + .. _dot render example: + + .. kernel-render:: DOT + :alt: digraph + :caption: Embedded DOT (Graphviz) code digraph foo { "bar" -> "baz"; } -How this will be rendered depends on the installed tools. If Graphviz is -installed, you will see an vector image. If not the raw markup is inserted as -*literal-block* (:ref:`hello_dot_render`). + Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot + render example`. -.. admonition:: DOT markup +Please note :ref:`build tools `. If Graphviz_ is +installed, you will see an vector image. If not, the raw markup is inserted as +*literal-block*. + +.. admonition:: kernel-render DOT :class: rst-example - .. _hello_dot_render: + .. _dot render example: .. kernel-render:: DOT - :alt: foobar digraph - :caption: Embedded **DOT** (Graphviz) code + :alt: digraph + :caption: Embedded DOT (Graphviz) code digraph foo { "bar" -> "baz"; } -The *render* directive has all the options known from the *figure* directive, -plus option ``caption``. If ``caption`` has a value, a *figure* node is -inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if -you want to refer it (:ref:`hello_svg_render`). - + Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot + render example`. ``kernel-render`` SVG --------------------- -.. code:: reST +A simple example of embedded SVG_ is shown in figure :ref:`svg render example`: + +.. code-block:: rst + + .. _svg render example: - .. kernel-render:: SVG markup + .. kernel-render:: SVG :caption: Embedded **SVG** markup :alt: so-nw-arrow .. - .. code:: xml + .. code:: xml - - - + + + -.. admonition:: SVG markup +.. admonition:: kernel-render SVG :class: rst-example - .. _hello_svg_render: + .. _svg render example: .. kernel-render:: SVG :caption: Embedded **SVG** markup :alt: so-nw-arrow - - - + + + + + .. _reST lists: List markups @@ -551,7 +593,7 @@ are mappings from field names to field bodies. They marked up like this: :fieldname: Field content :foo: first paragraph in field foo - second paragraph in field foo + second paragraph in field foo :bar: Field content @@ -561,7 +603,7 @@ are mappings from field names to field bodies. They marked up like this: :fieldname: Field content :foo: first paragraph in field foo - second paragraph in field foo + second paragraph in field foo :bar: Field content @@ -684,3 +726,9 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, .. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _linuxdoc: https://return42.github.io/linuxdoc +.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html +.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html +.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf +.. _Graphviz: https://graphviz.gitlab.io + +.. _ImageMagick: https://www.imagemagick.org -- cgit v1.2.3 From b201f8459527a9a186838d1325977fe950dd2f0a Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 20 Dec 2019 17:47:24 +0100 Subject: docs: reST-primer continued proofreading (WIP) Signed-off-by: Markus Heiser --- docs/dev/reST.rst | 168 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 119 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 8bab5e332..609517f6a 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -88,19 +88,23 @@ Developer's POV: :origin:`docs/dev` Basic inline markup =================== -``*italics*`` -- *italics* - one asterisk for emphasis +.. sidebar:: Inline markup -``**boldface**`` -- **boldface** - two asterisks for strong emphasis and + - :ref:`reST roles` + - :ref:`reST smart ref` -````foo()```` -- ``foo()`` - backquotes for code samples and literals. +Basic inline markup is done with asterisks and backquotes. If asterisks or +backquotes appear in running text and could be confused with inline markup +delimiters, they have to be escaped with a backslash (``\*pointer``). -``\*foo is a pointer`` -- \*foo is a pointer - If asterisks or backquotes appear in running text and could be confused with - inline markup delimiters, they have to be escaped with a backslash (``\*foo is - a pointer``). +================================================ ==================== ======================== +description rendered markup +================================================ ==================== ======================== +one asterisk for emphasis *italics* ``*italics*`` +two asterisks for strong emphasis **boldface** ``**boldface**`` +backquotes for code samples and literals ``foo()`` ````foo()```` +quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer`` +================================================ ==================== ======================== .. _reST basic structure: @@ -110,44 +114,82 @@ Basic article structure The basic structure of an article makes use of heading adornments to markup chapter, sections and subsections. -#. ``=`` with overline for document title -#. ``=`` for chapters -#. ``-`` for sections -#. ``~`` for subsections - .. _reST template: -.. admonition:: reST template - :class: rst-example +reST template +------------- - .. code:: reST +reST template for an simple article: + +.. code:: reST + + .. _doc refname: + + ============== + Document title + ============== + + Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read + :ref:`chapter refname`. + + .. _chapter refname: + + Chapter + ======= + + Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut + aliquid ex ea commodi consequat ... + + .. _section refname: + + Section + ------- - .. _document title: + lorem .. + + .. _subsection refname: + + Subsection + ~~~~~~~~~~ + + lorem .. + + +Headings +-------- + +#. title - with overline for document title: + + .. code:: reST + + ============== + Document title + ============== + + +#. chapter - with anchor named ``anchor name``: + + .. code:: reST - ============== - Document title - ============== + .. _anchor name: - Lorem ipsum dolor sit amet, consectetur adipisici elit .. - Further read :ref:`chapter title`. + Chapter + ======= - .. _chapter title: +#. section - Chapters - ======== + .. code:: reST - Ut enim ad minim veniam, quis nostrud exercitation ullamco - laboris nisi ut aliquid ex ea commodi consequat ... + Section + ------- - Section - ------- +#. subsection - lorem .. + .. code:: reST - Subsection - ~~~~~~~~~~ + Subsection + ~~~~~~~~~~ - lorem .. Anchors & Links @@ -179,18 +221,18 @@ To refer anchors use the `ref role`_ markup: .. code:: reST - Visit chapter :ref:`reST anchor`. - Or set hyperlink text manualy :ref:`foo bar `. + Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo + bar `. .. admonition:: ``:ref:`` role :class: rst-example - Visist chapter :ref:`reST anchor` - Or set hyperlink text manualy :ref:`foo bar `. + Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo + bar `. .. _reST ordinary ref: -link ordinary URL +Link ordinary URL ----------------- If you need to reference external URLs use *named* hyperlinks to maintain @@ -221,8 +263,8 @@ readability of reST sources. Here is a example taken from *this* article: .. _reST smart ref: -smart references ----------------- +Smart refs +---------- With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external content becomes smart. @@ -270,6 +312,8 @@ To list all anchors of the inventory (e.g. ``python``) use: $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv +.. _reST roles: + Roles ===== @@ -634,9 +678,24 @@ Further list blocks Admonitions =========== -Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, -:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, , -:dudir:`warning` and the generic :dudir:`admonition `. +Sidebar +------- + +Sidebar is an eye catcher, often used for admonitions pointing further stuff or +site effects. Here is the source of the sidebar :ref:`on top of this page `. + +.. code:: reST + + .. sidebar:: KISS_ and readability_ + + Instead of defining more and more roles, we at searx encourage our + contributors to follow principles like KISS_ and readability_. + +Generic admonition +------------------ + +The generic :dudir:`admonition ` needs a title: .. code:: reST @@ -644,6 +703,21 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, lorem ipsum .. + +.. admonition:: generic admonition title + + lorem ipsum .. + + +Specific admonitions +-------------------- + +Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, +:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and +:dudir:`warning` . + +.. code:: reST + .. hint:: lorem ipsum .. @@ -657,10 +731,6 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, lorem ipsum .. -.. admonition:: generic admonition title - - lorem ipsum .. - .. hint:: lorem ipsum .. -- cgit v1.2.3 From c2b9aa0c2fe5e9eee24619d2fe563da01d9ecf87 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 20 Dec 2019 20:39:14 +0100 Subject: docs: reST-primer describe table markup (WIP) Signed-off-by: Markus Heiser --- docs/dev/csv_table.txt | 6 + docs/dev/reST.rst | 423 ++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 376 insertions(+), 53 deletions(-) create mode 100644 docs/dev/csv_table.txt (limited to 'docs') diff --git a/docs/dev/csv_table.txt b/docs/dev/csv_table.txt new file mode 100644 index 000000000..8a1454137 --- /dev/null +++ b/docs/dev/csv_table.txt @@ -0,0 +1,6 @@ +stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy +eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam +voluptua." +stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita +kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column +stub col row 1, column, column diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 609517f6a..50caa0feb 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -97,14 +97,17 @@ Basic inline markup is done with asterisks and backquotes. If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash (``\*pointer``). -================================================ ==================== ======================== -description rendered markup -================================================ ==================== ======================== -one asterisk for emphasis *italics* ``*italics*`` -two asterisks for strong emphasis **boldface** ``**boldface**`` -backquotes for code samples and literals ``foo()`` ````foo()```` -quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer`` -================================================ ==================== ======================== +.. table:: basic inline markup + :widths: 4 3 7 + + ================================================ ==================== ======================== + description rendered markup + ================================================ ==================== ======================== + one asterisk for emphasis *italics* ``*italics*`` + two asterisks for strong emphasis **boldface** ``**boldface**`` + backquotes for code samples and literals ``foo()`` ````foo()```` + quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer`` + ================================================ ==================== ======================== .. _reST basic structure: @@ -269,27 +272,30 @@ Smart refs With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external content becomes smart. -========================== ================================== ==================================== -refer ... rendered example markup -========================== ================================== ==================================== -:rst:role:`rfc` :rfc:`822` ``:rfc:`822``` -:rst:role:`pep` :pep:`8` ``:pep:`8``` -sphinx.ext.extlinks_ --------------------------------------------------------------------------------------------------- -project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances``` -to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html``` -files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst``` -pull request :pull:`1756` ``:pull:`1756``` -patch :patch:`af2cae6` ``:patch:`af2cae6``` -PyPi package :pypi:`searx` ``:pypi:`searx``` -manual page man :man:`bash` ``:man:`bash``` -intersphinx_ --------------------------------------------------------------------------------------------------- -external anchor :ref:`python:and` ``:ref:`python:and``` -external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates``` -python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime``` -flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask``` -========================== ================================== ==================================== +.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_ + :widths: 4 3 7 + + ========================== ================================== ==================================== + refer ... rendered example markup + ========================== ================================== ==================================== + :rst:role:`rfc` :rfc:`822` ``:rfc:`822``` + :rst:role:`pep` :pep:`8` ``:pep:`8``` + sphinx.ext.extlinks_ + -------------------------------------------------------------------------------------------------- + project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances``` + to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html``` + files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst``` + pull request :pull:`1756` ``:pull:`1756``` + patch :patch:`af2cae6` ``:patch:`af2cae6``` + PyPi package :pypi:`searx` ``:pypi:`searx``` + manual page man :man:`bash` ``:man:`bash``` + intersphinx_ + -------------------------------------------------------------------------------------------------- + external anchor :ref:`python:and` ``:ref:`python:and``` + external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates``` + python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime``` + flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask``` + ========================== ================================== ==================================== Intersphinx is configured in :origin:`docs/conf.py`: @@ -317,30 +323,43 @@ To list all anchors of the inventory (e.g. ``python``) use: Roles ===== +.. sidebar:: Further reading + + - `Sphinx Roles`_ + - :doc:`sphinx:usage/restructuredtext/domains` + + A *custom interpreted text role* (:duref:`ref `) is an inline piece of explicit markup. It signifies that that the enclosed text should be interpreted -in a specific way. The general syntax is ``:rolename:`content```. - -========================== ================================== ==================================== -role rendered example markup -========================== ================================== ==================================== -:rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel``` -:rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f``` -:rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File``` -:rst:role:`download` :download:`this file ` ``:download:`this file ``` -:rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2``` -:rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example``` -:rst:role:`command` :command:`ls -la` ``:command:`ls -la``` -:durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic``` -:durole:`strong` :strong:`bold` ``:strong:`bold``` -:durole:`literal` :literal:`foo()` ``:literal:`foo()``` -:durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O`` -:durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2``` -:durole:`title-reference` :title:`Time` ``:title:`Time``` -========================== ================================== ==================================== - -Refer to `Sphinx Roles`_ for roles added by Sphinx. +in a specific way. + +The general markup is one of: + +.. code:: reST + :rolename:`ref-name` + :rolename:`ref text ` + +.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_ + :widths: 4 3 7 + + ========================== ================================== ==================================== + role rendered example markup + ========================== ================================== ==================================== + :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel``` + :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f``` + :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File``` + :rst:role:`download` :download:`this file ` ``:download:`this file ``` + :rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2``` + :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example``` + :rst:role:`command` :command:`ls -la` ``:command:`ls -la``` + :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic``` + :durole:`strong` :strong:`bold` ``:strong:`bold``` + :durole:`literal` :literal:`foo()` ``:literal:`foo()``` + :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O`` + :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2``` + :durole:`title-reference` :title:`Time` ``:title:`Time``` + ========================== ================================== ==================================== Figures & Images ================ @@ -420,7 +439,7 @@ Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the :ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is shown in figure :ref:`dot render example`: -.. code-block:: rst +.. code:: reST .. _dot render example: @@ -460,7 +479,7 @@ installed, you will see an vector image. If not, the raw markup is inserted as A simple example of embedded SVG_ is shown in figure :ref:`svg render example`: -.. code-block:: rst +.. code:: reST .. _svg render example: @@ -768,8 +787,302 @@ Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attenti lorem ipsum .. +Tables +====== + +.. sidebar:: Nested tables + + Nested tables are ugly! Not all builder support nested tables, don't use + them! + +ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might +be comfortable for readers of the text-files, but they have huge disadvantages +in the creation and modifying. First, they are hard to edit. Think about +adding a row or a column to a ASCII-art table or adding a paragraph in a cell, +it is a nightmare on big tables. + + +.. sidebar:: List tables + + For meaningful patch and diff use :ref:`reST flat table`. + +Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a +cell generates a diff in which also changes are included, which are only +ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason, +here are some helpers: + +* `Emacs Table Mode`_ +* `Online Tables Generator`_ + +.. _reST simple table: + +Simple tables +------------- + +:duref:`Simple tables ` allow *colspan* but not *rowspan*. If +your table need some metadata (e.g. a title) you need to add the ``.. table:: +directive`` :dudir:`(ref) ` in front and place the table in its body: + +.. code:: reST + + .. table:: foo gate truth table + :widths: grid + :align: left + + ====== ====== ====== + Inputs Output + ------------- ------ + A B A or B + ====== ====== ====== + False + -------------------- + True + -------------------- + True False True + (foo) + ------ ------ ------ + False True + (foo) + ====== ============= + +.. admonition:: Simple ASCII table + :class: rst-example + + .. table:: foo gate truth table + :widths: grid + :align: left + + ====== ====== ====== + Inputs Output + ------------- ------ + A B A or B + ====== ====== ====== + False + -------------------- + True + -------------------- + True False True + (foo) + ------ ------ ------ + False True + (foo) + ====== ============= + + + +.. _reST grid table: + +Grid tables +----------- + +:duref:`Grid tables ` allow colspan *colspan* and *rowspan*: + +.. code:: reST + + .. table:: grid table example + :widths: 1 1 5 + + +------------+------------+-----------+ + | Header 1 | Header 2 | Header 3 | + +============+============+===========+ + | body row 1 | column 2 | column 3 | + +------------+------------+-----------+ + | body row 2 | Cells may span columns.| + +------------+------------+-----------+ + | body row 3 | Cells may | - Cells | + +------------+ span rows. | - contain | + | body row 4 | | - blocks. | + +------------+------------+-----------+ + +.. admonition:: ASCII grid table + :class: rst-example + + .. table:: grid table example + :widths: 1 1 5 + + +------------+------------+-----------+ + | Header 1 | Header 2 | Header 3 | + +============+============+===========+ + | body row 1 | column 2 | column 3 | + +------------+------------+-----------+ + | body row 2 | Cells may span columns.| + +------------+------------+-----------+ + | body row 3 | Cells may | - Cells | + +------------+ span rows. | - contain | + | body row 4 | | - blocks. | + +------------+------------+-----------+ + + +.. _reST flat table: + +flat-table +---------- + +The ``flat-table`` is a further developed variant of the :ref:`list tables +`. It is a double-stage list similar to the +:dudir:`list-table` with some additional features: + +column-span: ``cspan`` + with the role ``cspan`` a cell can be extended through additional columns + +row-span: ``rspan`` + with the role ``rspan`` a cell can be extended through additional rows + +auto-span: + spans rightmost cell of a table row over the missing cells on the right side + of that table-row. With Option ``:fill-cells:`` this behavior can changed + from *auto span* to *auto fill*, which automatically inserts (empty) cells + instead of spanning the last cell. + +options: + :header-rows: [int] count of header rows + :stub-columns: [int] count of stub columns + :widths: [[int] [int] ... ] widths of columns + :fill-cells: instead of auto-span missing cells, insert missing cells + +roles: + :cspan: [int] additional columns (*morecols*) + :rspan: [int] additional rows (*morerows*) + +The example below shows how to use this markup. The first level of the staged +list is the *table-row*. In the *table-row* there is only one markup allowed, +the list of the cells in this *table-row*. Exception are *comments* ( ``..`` ) +and *targets* (e.g. a ref to :ref:`row 2 of table's body `). + +.. code:: reST + + .. flat-table:: ``flat-table`` example + :header-rows: 2 + :stub-columns: 1 + :widths: 1 1 1 1 2 + + * - :rspan:`1` head / stub + - :cspan:`3` head 1.1-4 + + * - head 2.1 + - head 2.2 + - head 2.3 + - head 2.4 + + * .. row body 1 / this is a comment + + - row 1 + - :rspan:`2` cell 1-3.1 + - cell 1.2 + - cell 1.3 + - cell 1.4 + + * .. Comments and targets are allowed on *table-row* stage. + .. _`row body 2`: + + - row 2 + - cell 2.2 + - :rspan:`1` :cspan:`1` + cell 2.3 with a span over + + * col 3-4 & + * row 2-3 + + * - row 3 + - cell 3.2 + + * - row 4 + - cell 4.1 + - cell 4.2 + - cell 4.3 + - cell 4.4 + + * - row 5 + - cell 5.1 with automatic span to rigth end + + * - row 6 + - cell 6.1 + - .. + + +.. admonition:: List table + :class: rst-example + + .. flat-table:: ``flat-table`` example + :header-rows: 2 + :stub-columns: 1 + :widths: 1 1 1 1 2 + + * - :rspan:`1` head / stub + - :cspan:`3` head 1.1-4 + + * - head 2.1 + - head 2.2 + - head 2.3 + - head 2.4 + + * .. row body 1 / this is a comment + + - row 1 + - :rspan:`2` cell 1-3.1 + - cell 1.2 + - cell 1.3 + - cell 1.4 + + * .. Comments and targets are allowed on *table-row* stage. + .. _`row body 2`: + + - row 2 + - cell 2.2 + - :rspan:`1` :cspan:`1` + cell 2.3 with a span over + + * col 3-4 & + * row 2-3 + + * - row 3 + - cell 3.2 + + * - row 4 + - cell 4.1 + - cell 4.2 + - cell 4.3 + - cell 4.4 + + * - row 5 + - cell 5.1 with automatic span to rigth end + + * - row 6 + - cell 6.1 + - .. + + +CSV table +--------- + +CSV table might be the choice if you want to include CSV-data from a outstanding +(build) process into your documentation. + +.. code:: reST + + .. csv-table:: CSV table example + :header: .. , Column 1, Column 2 + :widths: 2 5 5 + :stub-columns: 1 + :file: csv_table.txt + +Content of file ``csv_table.txt``: + +.. literalinclude:: csv_table.txt + +.. admonition:: CSV table + :class: rst-example + + .. csv-table:: CSV table example + :header: .. , Column 1, Column 2 + :widths: 3 5 5 + :stub-columns: 1 + :file: csv_table.txt + + .. _KISS: https://en.wikipedia.org/wiki/KISS_principle + .. _readability: https://docs.python-guide.org/writing/style/ .. _Sphinx-Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html @@ -796,9 +1109,13 @@ Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attenti .. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _linuxdoc: https://return42.github.io/linuxdoc + .. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html .. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html .. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf .. _Graphviz: https://graphviz.gitlab.io - .. _ImageMagick: https://www.imagemagick.org + +.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode +.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables +.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html -- cgit v1.2.3 From d1154202bcd27a7cf3a1bed524ee6b24955df8af Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 21 Dec 2019 17:13:38 +0100 Subject: doc: add reST templating // incl. generic engine tabe Signed-off-by: Markus Heiser --- docs/admin/engines.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++ docs/admin/index.rst | 1 + docs/conf.py | 10 ++++--- docs/dev/engine_overview.rst | 2 ++ docs/dev/reST.rst | 34 +++++++++++++++++++++- docs/dev/search_api.rst | 7 +++++ 6 files changed, 117 insertions(+), 5 deletions(-) create mode 100644 docs/admin/engines.rst (limited to 'docs') diff --git a/docs/admin/engines.rst b/docs/admin/engines.rst new file mode 100644 index 000000000..40c3b9e4f --- /dev/null +++ b/docs/admin/engines.rst @@ -0,0 +1,68 @@ +.. _engines generic: + +======= +engines +======= + +.. sidebar:: Further reading .. + + - :ref:`engines generic` + - :ref:`configured engines` + - :ref:`engine settings` + - :ref:`engine file` + +============= =========== ==================== ============ +:ref:`engine settings` :ref:`engine file` +------------------------- --------------------------------- +Name (cfg) Categories +------------------------- --------------------------------- +Engine .. Paging support **P** +------------------------- -------------------- ------------ +Shortcut **S** Language support **L** +Timeout **TO** Time range support **TR** +Disabled **D** Offline **O** +------------- ----------- -------------------- ------------ +Suspend end **SE** +------------- ----------- --------------------------------- +Safe search **SS** +============= =========== ================================= + +Configuration defaults (at built time): + +.. _configured engines: + +.. jinja:: webapp + + .. flat-table:: Engines configured at built time (defaults) + :header-rows: 1 + :stub-columns: 2 + + * - Name (cfg) + - S + - Engine + - TO + - Categories + - P + - L + - SS + - D + - TR + - O + - SE + + {% for name, mod in engines.items() %} + + * - {{name}} + - !{{mod.shortcut}} + - {{mod.__name__}} + - {{mod.timeout}} + - {{", ".join(mod.categories)}} + - {{(mod.paging and "y") or ""}} + - {{(mod.language_support and "y") or ""}} + - {{(mod.safesearch and "y") or ""}} + - {{(mod.disabled and "y") or ""}} + - {{(mod.time_range_support and "y") or ""}} + - {{(mod.offline and "y") or ""}} + - {{mod.suspend_end_time}} + + {% endfor %} diff --git a/docs/admin/index.rst b/docs/admin/index.rst index f3a995769..6e9a3451f 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -9,3 +9,4 @@ Administrator documentation api filtron morty + engines diff --git a/docs/conf.py b/docs/conf.py index b960621d3..e49562a33 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,11 @@ master_doc = "index" source_suffix = '.rst' numfig = True +from searx import webapp +jinja_contexts = { + 'webapp': dict(**webapp.__dict__) +} + # usage:: lorem :patch:`f373169` ipsum extlinks = {} @@ -52,11 +57,8 @@ 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 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive. - 'linuxdoc.rstKernelDoc', # Implementation of the 'kernel-doc' reST-directive. - 'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive. - 'linuxdoc.manKernelDoc', # Implementation of the 'kernel-doc-man' builder - 'linuxdoc.cdomain', # Replacement for the sphinx c-domain. 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling. ] diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 92405dc64..449c837a9 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -29,6 +29,7 @@ the ones in the engine file. It does not matter if an option is stored in the engine file or in the settings. However, the standard way is the following: +.. _engine file: engine file ----------- @@ -43,6 +44,7 @@ time_range_support boolean support search time range offline boolean engine runs offline ======================= =========== =========================================== +.. _engine settings: settings.yml ------------ diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 50caa0feb..9e90c8c64 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -26,6 +26,7 @@ The sources of Searx's documentation are located at :origin:`docs`. Run - `sphinx cross references`_ - linuxdoc_ - intersphinx_ + - sphinx-jinja_ - `Sphinx's autodoc`_ - `Sphinx's Python domain`_, `Sphinx's C domain`_ - SVG_, ImageMagick_ @@ -1079,6 +1080,36 @@ Content of file ``csv_table.txt``: :stub-columns: 1 :file: csv_table.txt +Templating +========== + +.. sidebar:: Build environment + + All *generic-doc* tasks are running in the :ref:`build environment `. + +Templating is suitable for documentation which is created generic at the build +time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build +environment ` with installed searx modules. We use this e.g. to +build chapter: :ref:`engines generic`. + +Here is the content of the :origin:`docs/admin/engines.rst`: + +.. literalinclude:: ../admin/engines.rst + :language: reST + :start-after: .. _configured engines: + +The context for the template is selected in the line ``.. jinja:: webapp``. In +sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context +points to the name space of the python module: ``webapp``. + +.. code:: py + + from searx import webapp + jinja_contexts = { + 'webapp': dict(**webapp.__dict__) + } + .. _KISS: https://en.wikipedia.org/wiki/KISS_principle @@ -1109,7 +1140,8 @@ Content of file ``csv_table.txt``: .. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _linuxdoc: https://return42.github.io/linuxdoc - +.. _jinja: https://jinja.palletsprojects.com/ +.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja .. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html .. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html .. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 158cab7c5..8ca804b8c 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -14,6 +14,13 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying. Parameters ========== +.. sidebar:: Further reading .. + + - :ref:`engines generic` + - :ref:`configured engines` + - :ref:`engine settings` + - :ref:`engine file` + ``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 -- cgit v1.2.3 From 5bdca1a5bfeb825dd1efab426a6f5ec31efba7d0 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 22 Dec 2019 11:46:03 +0100 Subject: doc: improved HTML table layout (CSS) Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 10cfc413e..347fc71ab 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -89,3 +89,35 @@ div.rst-example { display: none; } } + +/* Table theme +*/ + + +thead, tfoot { + background-color: #fff; +} + +th:hover, td:hover { + background-color: #ffc; +} + +thead th, tfoot th, tfoot td, tbody th { + background-color: #fffaef; +} + +tbody tr:nth-child(odd) { + background-color: #fff; +} + +tbody tr:nth-child(even) { + background-color: #fafafa; +} + +caption { + font-family: Sans Serif; + padding: 0.5em; + margin: 0.5em 0 0.5em 0; + caption-side: top; + text-align: left; +} -- cgit v1.2.3 From aa3b0265e761eec07055d8f248d677a5cb4e8725 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 22 Dec 2019 14:05:33 +0100 Subject: doc: add 'Architecture' article to admin section Herein we add some hints and suggestions about typical architectures of searx infrastructures. We start with a contribution from @dalf - https://github.com/asciimoo/searx/pull/1776#issuecomment-567917320 thanks @dalf !! Signed-off-by: Markus Heiser --- docs/admin/arch_public.dot | 33 +++++++++++++++++++++++++++++++++ docs/admin/architecture.rst | 24 ++++++++++++++++++++++++ docs/admin/index.rst | 1 + docs/dev/contribution_guide.rst | 2 ++ 4 files changed, 60 insertions(+) create mode 100644 docs/admin/arch_public.dot create mode 100644 docs/admin/architecture.rst (limited to 'docs') diff --git a/docs/admin/arch_public.dot b/docs/admin/arch_public.dot new file mode 100644 index 000000000..a46c96de3 --- /dev/null +++ b/docs/admin/arch_public.dot @@ -0,0 +1,33 @@ +digraph G { + + node [style=filled, shape=box, fillcolor="#ffffcc", fontname="Sans"]; + edge [fontname="Sans"]; + + browser [label="Browser", shape=Mdiamond]; + rp [label="Reverse Proxy", href="url to configure reverse proxy"]; + filtron [label="Filtron", href="https://github.com/asciimoo/filtron"]; + morty [label="Morty", href="https://github.com/asciimoo/morty"]; + static [label="Static files", href="url to configure static files"]; + uwsgi [label="uwsgi", href="url to configure uwsgi"] + searx1 [label="Searx #1"]; + searx2 [label="Searx #2"]; + searx3 [label="Searx #3"]; + searx4 [label="Searx #4"]; + + browser -> rp [label="HTTPS"] + + subgraph cluster_searx { + label = "Searx instance" fontname="Sans"; + bgcolor="#fafafa"; + { rank=same; static rp }; + rp -> morty [label="optional: images and HTML pages proxy"]; + rp -> static [label="optional: reverse proxy serves directly static files"]; + rp -> filtron [label="HTTP"]; + filtron -> uwsgi [label="HTTP"]; + uwsgi -> searx1; + uwsgi -> searx2; + uwsgi -> searx3; + uwsgi -> searx4; + } + +} diff --git a/docs/admin/architecture.rst b/docs/admin/architecture.rst new file mode 100644 index 000000000..7064a294b --- /dev/null +++ b/docs/admin/architecture.rst @@ -0,0 +1,24 @@ +.. _architecture: + +============ +Architecture +============ + +.. sidebar:: Needs work! + + This article needs some work / Searx is a collaborative effort. If you have + any contribution, feel welcome to send us your :pull:`PR <../pulls>`, see + :ref:`how to contribute`. + +Herein you will find some hints and suggestions about typical architectures of +searx infrastructures. + +We start with a contribution from :pull:`@dalf <1776#issuecomment-567917320>`. +It shows a *reference* setup for public searx instances. + +.. _arch public: + +.. kernel-figure:: arch_public.dot + :alt: arch_public.dot + + Reference architecture of a public searx setup. diff --git a/docs/admin/index.rst b/docs/admin/index.rst index 6e9a3451f..1b05db42d 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -7,6 +7,7 @@ Administrator documentation installation api + architecture filtron morty engines diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 6d8d3924d..ccc101d2e 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -1,3 +1,5 @@ +.. _how to contribute: + ================= How to contribute ================= -- cgit v1.2.3 From 31db843c9c1f66da4ab2f8f23f969a0671ae6e65 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 22 Dec 2019 14:08:57 +0100 Subject: doc: CSS - fix alignment of code block in figure blocks BTW: minor profread of reST.rst Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 8 +++++++- docs/dev/reST.rst | 7 +++---- 2 files changed, 10 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 347fc71ab..05bbb49da 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -90,10 +90,16 @@ div.rst-example { } } +/* code block in figures + */ + +div.highlight pre { + text-align: left; +} + /* Table theme */ - thead, tfoot { background-color: #fff; } diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 9e90c8c64..ff76ea91e 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -1090,10 +1090,9 @@ Templating Templating is suitable for documentation which is created generic at the build time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build -environment ` with installed searx modules. We use this e.g. to -build chapter: :ref:`engines generic`. - -Here is the content of the :origin:`docs/admin/engines.rst`: +environment ` (with searx modules installed). We use this e.g. to +build chapter: :ref:`engines generic`. Below the jinja directive from the +:origin:`docs/admin/engines.rst` is shown: .. literalinclude:: ../admin/engines.rst :language: reST -- cgit v1.2.3 From 90174e215c2eeb44ad8d76d7389ec5f661e63b82 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 22 Dec 2019 23:26:06 +0100 Subject: doc: add plugin section to admin section (template) - Plugins configured at built time (defaults) Signed-off-by: Markus Heiser --- docs/admin/index.rst | 1 + docs/admin/plugins.rst | 39 +++++++++++++++++++++++++++++++++++++++ docs/dev/plugins.rst | 6 ++++++ 3 files changed, 46 insertions(+) create mode 100644 docs/admin/plugins.rst (limited to 'docs') diff --git a/docs/admin/index.rst b/docs/admin/index.rst index 1b05db42d..c08cadb67 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -11,3 +11,4 @@ Administrator documentation filtron morty engines + plugins diff --git a/docs/admin/plugins.rst b/docs/admin/plugins.rst new file mode 100644 index 000000000..4ed9066fd --- /dev/null +++ b/docs/admin/plugins.rst @@ -0,0 +1,39 @@ +.. _plugins generic: + +=============== +Plugins builtin +=============== + +.. sidebar:: Further reading .. + + - :ref:`dev plugin` + +Configuration defaults (at built time): + +:DO: Default on + +.. _configured plugins: + +.. jinja:: webapp + + .. flat-table:: Plugins configured at built time (defaults) + :header-rows: 1 + :stub-columns: 1 + :widths: 3 1 9 + + * - Name + - DO + - Description + + JS & CSS dependencies + + {% for plgin in plugins %} + + * - {{plgin.name}} + - {{(plgin.default_on and "y") or ""}} + - {{plgin.description}} + + {% for dep in (plgin.js_dependencies + plgin.css_dependencies) %} + | ``{{dep}}`` {% endfor %} + + {% endfor %} diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst index e97bbeb4a..2bf44f181 100644 --- a/docs/dev/plugins.rst +++ b/docs/dev/plugins.rst @@ -1,7 +1,13 @@ +.. _dev plugin: + ======= Plugins ======= +.. sidebar:: Further reading .. + + - :ref:`plugins generic` + Plugins can extend or replace functionality of various components of searx. Example plugin -- cgit v1.2.3 From c8645d6e376ba5a072be370d12efdec298f4e3ad Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 23 Dec 2019 09:37:51 +0100 Subject: doc: reST-primer -- imrpove desription of definition lists Signed-off-by: Markus Heiser --- docs/dev/reST.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index ff76ea91e..c6aa990f2 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -574,32 +574,70 @@ List markup (:duref:`ref `) is simple: Definition list --------------- -.. sidebar:: definition term +.. sidebar:: Note .. - Note that the term cannot have more than one line of text. + - the term cannot have more than one line of text -Definition lists (:duref:`ref `) are created as follows: + - there is **no blank line between term and definition block** // this + distinguishes definition lists (:duref:`ref `) from block + quotes (:duref:`ref `). + +Each definition list (:duref:`ref `) item contains a term, +optional classifiers and a definition. A term is a simple one-line word or +phrase. Optional classifiers may follow the term on the same line, each after +an inline ' : ' (**space, colon, space**). A definition is a block indented +relative to the term, and may contain multiple paragraphs and other body +elements. There may be no blank line between a term line and a definition block +(*this distinguishes definition lists from block quotes*). Blank lines are +required before the first and after the last definition list item, but are +optional in-between. + +Definition lists are created as follows: .. code:: reST - term (up to a line of text) - Definition of the term, which must be indented + term 1 (up to a line of text) + Definition 1. + + See the typo : this line is not a term! + + And this is not term's definition. **There is a blank line** in between + the line above and this paragraph. That's why this paragraph is taken as + **block quote** (:duref:`ref `) and not as term's definition! + + term 2 + Definition 2, paragraph 1. + + Definition 2, paragraph 2. - and can even consist of multiple paragraphs + term 3 : classifier + Definition 3. - next term - Description. + term 4 : classifier one : classifier two + Definition 4. .. admonition:: definition list :class: rst-example - term (up to a line of text) - Definition of the term, which must be indented + term 1 (up to a line of text) + Definition 1. + + See the typo : this line is not a term! + + And this is not term's definition. **There is a blank line** in between + the line above and this paragraph. That's why this paragraph is taken as + **block quote** (:duref:`ref `) and not as term's definition! + + + term 2 + Definition 2, paragraph 1. + + Definition 2, paragraph 2. - and can even consist of multiple paragraphs + term 3 : classifier + Definition 3. - next term - Description. + term 4 : classifier one : classifier two Quoted paragraphs -- cgit v1.2.3 From 4ca8b69c81ddbd965ff88deeaed7bc4f0709fbf4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 24 Dec 2019 18:48:23 +0100 Subject: doc(dev): add remarks about creating good commits (messages) preview (don't bookmark): https://return42.github.io/searx/dev/contribution_guide.html#code Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index ccc101d2e..c6030fbe3 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -50,6 +50,16 @@ Code ==== .. _PEP8: https://www.python.org/dev/peps/pep-0008/ +.. _Conventional Commits: https://www.conventionalcommits.org/ +.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages +.. _Structural split of changes: + https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes + +.. sidebar:: Create good commits! + + - `Structural split of changes`_ + - `Conventional Commits`_ + - `Git Commit Good Practice`_ In order to submit a patch, please follow the steps below: @@ -59,6 +69,9 @@ In order to submit a patch, please follow the steps below: - PEP8_ standards apply, except the convention of line length - Maximum line length is 120 characters +- The cardinal rule for creating good commits is to ensure there is only one + *logical change* per commit / read `Structural split of changes`_ + - Check if your code breaks existing tests. If so, update the tests or fix your code. @@ -66,6 +79,16 @@ In order to submit a patch, please follow the steps below: - Add yourself to the :origin:`AUTHORS.rst` file. +- Choose meaning full commit messages, read `Conventional Commits`_ + + .. code:: + + [optional scope]: + + [optional body] + + [optional footer(s)] + - Create a pull request. For more help on getting started with searx development, see :ref:`devquickstart`. -- cgit v1.2.3 From 62505f8982c2bc2cae5456a7ab50932fea580cc4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 25 Dec 2019 09:57:21 +0100 Subject: docs(dev): add refs to to gitmoji and Semantic PR in contrib section preview (don't bookmark): https://return42.github.io/searx/dev/contribution_guide.html#code Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index c6030fbe3..459dfb448 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -54,13 +54,16 @@ Code .. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages .. _Structural split of changes: https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes +.. _gitmoji: https://gitmoji.carloscuesta.me/ +.. _Semantic PR: https://github.com/zeke/semantic-pull-requests .. sidebar:: Create good commits! - `Structural split of changes`_ - `Conventional Commits`_ - `Git Commit Good Practice`_ - + - some like to use: gitmoji_ + - not yet active: `Semantic PR`_ In order to submit a patch, please follow the steps below: -- cgit v1.2.3 From 92afe68d6532c93d455b7eafb827cc18b812a327 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 26 Dec 2019 10:26:12 +0100 Subject: doc(dev): reST/sphinx add tabbed views extension (sphinx_tabs.tabs) See issue #1785: idea: in the doc, provide installation instructions with one tab per distrubution preview (don't bookmark): https://return42.github.io/searx/dev/reST.html#tabbed-views Signed-off-by: Markus Heiser --- docs/conf.py | 1 + docs/dev/reST.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index e49562a33..b07e020d1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,6 +60,7 @@ extensions = [ "sphinxcontrib.jinja", # https://github.com/tardyp/sphinx-jinja '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 ] intersphinx_mapping = { diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index c6aa990f2..edd7e19b7 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -1148,6 +1148,81 @@ points to the name space of the python module: ``webapp``. } +Tabbed views +============ + +.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs +.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs +.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs +.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs + +With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation +instructions with one tab per distribution we use the `group-tabs`_ directive, +others are basic-tabs_ and code-tabs_. + + +.. code:: reST + + .. tabs:: + + .. group-tab:: Linux + + Linux Line 1 + + .. group-tab:: Mac OSX + + Mac OSX Line 1 + + .. group-tab:: Windows + + Windows Line 1 + + .. tabs:: + + .. group-tab:: Linux + + Linux Line 1 + + .. group-tab:: Mac OSX + + Mac OSX Line 1 + + .. group-tab:: Windows + + Windows Line 1 + + +.. admonition:: Tabbed view (grouped) + :class: rst-example + + .. tabs:: + + .. group-tab:: Linux + + Linux Line 1 + + .. group-tab:: Mac OSX + + Mac OSX Line 1 + + .. group-tab:: Windows + + Windows Line 1 + + .. tabs:: + + .. group-tab:: Linux + + Linux Line 1 + + .. group-tab:: Mac OSX + + Mac OSX Line 1 + + .. group-tab:: Windows + + Windows Line 1 + .. _KISS: https://en.wikipedia.org/wiki/KISS_principle -- cgit v1.2.3 From d6f2802e4b6066b718e86ab53ea168ab2a3394e9 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 28 Dec 2019 01:01:11 +0100 Subject: docs(dev): add more markups to reST primer - Literal blocks - Unicode substitution - Horizontal list - Math equations Signed-off-by: Markus Heiser --- docs/conf.py | 2 + docs/dev/reST.rst | 265 +++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 216 insertions(+), 51 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index b07e020d1..e041428ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,6 +49,8 @@ extlinks['durole'] = ( 'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '') extlinks['dudir'] = ( 'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '') +extlinks['ctan'] = ( + 'https://ctan.org/pkg/%s', 'CTAN: ') extensions = [ 'sphinx.ext.extlinks', diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index edd7e19b7..4dc1279f0 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -11,10 +11,12 @@ reST primer We at searx are using reStructuredText (aka reST_) markup for all kind of documentation, with the builders from the Sphinx_ project a HTML output is -generated and deployed at :docs:`github.io <.>`. +generated and deployed at :docs:`github.io <.>`. For build prerequisites read +:ref:`docs build`. -The sources of Searx's documentation are located at :origin:`docs`. Run -:ref:`make docs-live ` to build HTML while editing. +The source files of Searx's documentation are located at :origin:`docs`. Sphinx +assumes source files to be encoded in UTF-8 by defaul. Run :ref:`make docs-live +` to build HTML while editing. .. sidebar:: Further reading @@ -318,6 +320,123 @@ To list all anchors of the inventory (e.g. ``python``) use: $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv +Literal blocks +============== + +The simplest form of :duref:`literal-blocks` is a indented block introduced by +two colons (``::``). For highlighting use :dudir:`highlight` or :ref:`reST +code` directive. To include literals from external files use directive +:dudir:`literalinclude`. + +.. _reST literal: + +``::`` +------ + +.. code:: reST + + :: + + Literal block + + Lorem ipsum dolor:: + + Literal block + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy + eirmod tempor invidunt ut labore :: + + Literal block + +.. admonition:: Literal block + :class: rst-example + + :: + + Literal block + + Lorem ipsum dolor:: + + Literal block + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy + eirmod tempor invidunt ut labore :: + + Literal block + + +.. _reST code: + +``code-block`` +-------------- + +.. _pygments: https://pygments.org/languages/ + +.. sidebar:: Syntax highlighting + + is handled by pygments_. + +The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive +with additional options. To learn more about code literals visit +:ref:`sphinx:code-examples`. + +.. code-block:: reST + + The URL ``/stats`` handle is shown in :ref:`stats-handle` + + .. code-block:: Python + :caption: python code block + :name: stats-handle + + @app.route('/stats', methods=['GET']) + def stats(): + """Render engine statistics page.""" + stats = get_engines_stats() + return render( + 'stats.html' + , stats = stats ) + +.. code-block:: reST + +.. admonition:: Code block + :class: rst-example + + The URL ``/stats`` handle is shown in :ref:`stats-handle` + + .. code-block:: Python + :caption: python code block + :name: stats-handle + + @app.route('/stats', methods=['GET']) + def stats(): + """Render engine statistics page.""" + stats = get_engines_stats() + return render( + 'stats.html' + , stats = stats ) + +Unicode substitution +==================== + +The :dudir:`unicode directive ` converts Unicode +character codes (numerical values) to characters. This directive can only be +used within a substitution definition. + +.. code-block:: reST + + .. |copy| unicode:: 0xA9 .. copyright sign + .. |(TM)| unicode:: U+2122 + + Trademark |(TM)| and copyright |copy| glyphs. + +.. admonition:: Unicode + :class: rst-example + + .. |copy| unicode:: 0xA9 .. copyright sign + .. |(TM)| unicode:: U+2122 + + Trademark |(TM)| and copyright |copy| glyphs. + .. _reST roles: @@ -351,7 +470,7 @@ The general markup is one of: :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f``` :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File``` :rst:role:`download` :download:`this file ` ``:download:`this file ``` - :rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2``` + math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2``` :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example``` :rst:role:`command` :command:`ls -la` ``:command:`ls -la``` :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic``` @@ -371,16 +490,17 @@ Figures & Images is flexible. To get best results in the generated output format, install ImageMagick_ and Graphviz_. -Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means; -scalable in sense of the build process. Normally in absence of a converter +Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means; +scaleable in sense of the build process. Normally in absence of a converter tool, the build process will break. From the authors POV it’s annoying to care about the build process when handling with images, especially since he has no access to the build process. With :ref:`linuxdoc:kfigure` the build process continues and scales output quality in dependence of installed image processors. -If you want to add an image, you should use the ``kernel-figure`` and -``kernel-image`` directives. E.g. to insert a figure with a scalable image -format use SVG (:ref:`svg image example`): +If you want to add an image, you should use the ``kernel-figure`` (inheritance +of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`) +directives. E.g. to insert a figure with a scaleable image format use SVG +(:ref:`svg image example`): .. code:: reST @@ -389,7 +509,7 @@ format use SVG (:ref:`svg image example`): .. kernel-figure:: svg_image.svg :alt: SVG image example - simple SVG image + Simple SVG image To refer the figure, a caption block is needed: :ref:`svg image example`. @@ -398,7 +518,7 @@ format use SVG (:ref:`svg image example`): .. kernel-figure:: svg_image.svg :alt: SVG image example - simple SVG image + Simple SVG image. To refer the figure, a caption block is needed: :ref:`svg image example`. @@ -571,6 +691,35 @@ List markup (:duref:`ref `) is simple: #. It has two items too. +Horizontal list +--------------- + +The :rst:dir:`.. hlist:: ` transforms a bullet list into a more compact +list. + +.. code:: reST + + .. hlist:: + + - first list item + - second list item + - third list item + ... + +.. admonition:: hlist + :class: rst-example + + .. hlist:: + + - first list item + - second list item + - third list item + - next list item + - next list item xxxx + - next list item yyyy + - next list item zzzz + + Definition list --------------- @@ -1158,70 +1307,84 @@ Tabbed views With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation instructions with one tab per distribution we use the `group-tabs`_ directive, -others are basic-tabs_ and code-tabs_. - - -.. code:: reST - - .. tabs:: - - .. group-tab:: Linux +others are basic-tabs_ and code-tabs_. Below a *group-tab* example from +:ref:`docs build` is shown: - Linux Line 1 +.. literalinclude:: ../admin/buildhosts.rst + :language: reST + :start-after: .. _system requirements: + :end-before: .. _system requirements END: - .. group-tab:: Mac OSX - Mac OSX Line 1 +.. _math: - .. group-tab:: Windows +Math equations +============== - Windows Line 1 +.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics +.. _amsmath user guide: + http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf - .. tabs:: +.. sidebar:: About LaTeX - .. group-tab:: Linux + - `amsmath user guide`_ + - Mathematics_ + - :ref:`docs build` - Linux Line 1 +The input language for mathematics is LaTeX markup using the :ctan:`amsmath` +package. - .. group-tab:: Mac OSX +To embed LaTeX markup in reST documents, use role :rst:role:`:math: ` for +inline and directive :rst:dir:`.. math:: ` for block markup. - Mac OSX Line 1 +.. code:: reST - .. group-tab:: Windows + In :math:numref:`schroedinger general` the time-dependent Schrödinger equation + is shown. - Windows Line 1 + .. math:: + :label: schroedinger general + \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle = + \hat{H} |\,\psi (t) \rangle. -.. admonition:: Tabbed view (grouped) +.. admonition:: LaTeX math equation :class: rst-example - .. tabs:: - - .. group-tab:: Linux - - Linux Line 1 - - .. group-tab:: Mac OSX + In :math:numref:`schroedinger general` the time-dependent Schrödinger equation + is shown. - Mac OSX Line 1 + .. math:: + :label: schroedinger general - .. group-tab:: Windows + \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle = + \hat{H} |\,\psi (t) \rangle. - Windows Line 1 - .. tabs:: +The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac`` +(*displaystyle*) used in a inline markup or another fraction. - .. group-tab:: Linux - - Linux Line 1 - - .. group-tab:: Mac OSX +.. code:: reST - Mac OSX Line 1 + ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}` + ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}` - .. group-tab:: Windows +.. admonition:: Line spacing + :class: rst-example - Windows Line 1 + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy + eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam + voluptua. ... + ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}` + At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd + gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy + eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam + voluptua. ... + ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}` + At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd + gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. .. _KISS: https://en.wikipedia.org/wiki/KISS_principle -- cgit v1.2.3 From d1892b211268d958e4134c82328ba1e6065a7fa3 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 28 Dec 2019 01:25:16 +0100 Subject: docs(admin): add article 'Buildhosts' with system requirements Signed-off-by: Markus Heiser --- docs/admin/buildhosts.rst | 103 ++++++++++++++++++++++++++++++++++++++++++++++ docs/admin/index.rst | 1 + docs/conf.py | 8 +++- 3 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 docs/admin/buildhosts.rst (limited to 'docs') diff --git a/docs/admin/buildhosts.rst b/docs/admin/buildhosts.rst new file mode 100644 index 000000000..5260da033 --- /dev/null +++ b/docs/admin/buildhosts.rst @@ -0,0 +1,103 @@ +.. _buildhosts: + +========== +Buildhosts +========== + +.. sidebar:: This article needs some work + + If you have any contribution send us your :pull:`PR <../pulls>`, see + :ref:`how to contribute`. + +To get best results from build, its recommend to install additional packages +on build hosts. + +.. _docs build: + +Build docs +========== + +.. _Graphviz: https://graphviz.gitlab.io +.. _ImageMagick: https://www.imagemagick.org +.. _XeTeX: https://tug.org/xetex/ +.. _dvisvgm: https://dvisvgm.de/ + +.. sidebar:: Sphinx build needs + + - ImageMagick_ + - Graphviz_ + - XeTeX_ + - dvisvgm_ + +Most of the sphinx requirements are installed from :origin:`setup.py` and the +docs can be build from scratch with ``make docs``. For better math and image +processing additional packages are needed. The XeTeX_ needed not only for PDF +creation, its also needed for :ref:`math` when HTML output is build. + +To be able to do :ref:`sphinx:math-support` without CDNs, the math are rendered +as images (``sphinx.ext.imgmath`` extension). If your docs build (``make +docs``) shows warnings like this:: + + WARNING: dot(1) not found, for better output quality install \ + graphviz from http://www.graphviz.org + .. + WARNING: LaTeX command 'latex' cannot be run (needed for math \ + display), check the imgmath_latex setting + +you need to install additional packages on your build host, to get better HTML +output. + +.. _system requirements: + +.. tabs:: + + .. group-tab:: Ubuntu / debian + + .. code-block:: sh + + $ sudo apt install graphviz imagemagick texlive-xetex librsvg2-bin + + .. group-tab:: Arch Linux + + .. code-block:: sh + + $ sudo pacman -S graphviz imagemagick texlive-bin extra/librsvg + + .. group-tab:: Fedora / RHEL + + .. code-block:: sh + + $ sudo dnf install graphviz graphviz-gd texlive-xetex-bin librsvg2-tools + + +For PDF output you also need: + +.. tabs:: + + .. group-tab:: Ubuntu / debian + + .. code:: sh + + $ sudo apt texlive-latex-recommended texlive-extra-utils ttf-dejavu + + .. group-tab:: Arch Linux + + .. code:: sh + + $ sudo pacman -S texlive-core texlive-latexextra ttf-dejavu + + .. group-tab:: Fedora / RHEL + + .. code:: sh + + $ sudo dnf install \ + texlive-collection-fontsrecommended texlive-collection-latex \ + dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts + +.. _system requirements END: + +.. literalinclude:: ../conf.py + :language: python + :start-after: # sphinx.ext.imgmath setup + :end-before: # sphinx.ext.imgmath setup END + diff --git a/docs/admin/index.rst b/docs/admin/index.rst index c08cadb67..7799343be 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -12,3 +12,4 @@ Administrator documentation morty engines plugins + buildhosts diff --git a/docs/conf.py b/docs/conf.py index e041428ff..be0c9d6ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,7 @@ extlinks['ctan'] = ( 'https://ctan.org/pkg/%s', 'CTAN: ') extensions = [ + 'sphinx.ext.imgmath', 'sphinx.ext.extlinks', 'sphinx.ext.viewcode', "sphinx.ext.autodoc", @@ -79,10 +80,15 @@ issues_github_path = "asciimoo/searx" # HTML ----------------------------------------------------------------- sys.path.append(os.path.abspath('_themes')) - html_theme_path = ['_themes'] html_theme = "searx" +# sphinx.ext.imgmath setup +html_math_renderer = 'imgmath' +imgmath_image_format = 'svg' +imgmath_font_size = 14 +# sphinx.ext.imgmath setup END + html_theme_options = {"index_sidebar_logo": True} html_context = { "project_links": [ -- cgit v1.2.3 From b91e07bbf156241f6236b7e26d389e10e37553a3 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 28 Dec 2019 01:26:24 +0100 Subject: docs(css): render HTML rst-example slightly more discreet Signed-off-by: Markus Heiser --- docs/_themes/searx/static/searx.css | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css index 05bbb49da..d6a664f0f 100644 --- a/docs/_themes/searx/static/searx.css +++ b/docs/_themes/searx/static/searx.css @@ -24,10 +24,12 @@ p.sidebar-title, .sidebar p { margin: 6pt; } -.sidebar li { +.sidebar li, +.hlist li { list-style-type: disclosure-closed; } + /* admonitions */ @@ -69,25 +71,24 @@ p.admonition-title:after { */ div.rst-example { - padding-left: 12px; - padding-right: 12px; background-color: inherit; - transform: scale(0.9); - transition: transform 1s; + margin: 0; + border-top: none; + border-right: 1px solid #ccc; + border-bottom: none; border-left: none; + border-radius: none; + padding: 0; } -@media screen { - div.rst-example:hover { - transform: scale(1); - padding-left: inherit; - padding-right: inherit; - border-left: inherit; - } - - div.rst-example:hover > .admonition-title { - display: none; - } +div.rst-example > p.admonition-title { + font-family: Sans Serif; + font-style: italic; + font-size: 0.8em; + display: block; + border-bottom: 1px solid #ccc; + padding: 0.5em 1em; + text-align: right; } /* code block in figures -- cgit v1.2.3 From 10997a01e012502fedb691deb6ad220a09b4f9ed Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 30 Dec 2019 20:29:37 +0100 Subject: docs(admin): add weight & disabled cols to engine table BTW: remove internal suspend_end_time Signed-off-by: Markus Heiser --- docs/admin/engines.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/admin/engines.rst b/docs/admin/engines.rst index 40c3b9e4f..c1c69bb0b 100644 --- a/docs/admin/engines.rst +++ b/docs/admin/engines.rst @@ -1,7 +1,7 @@ .. _engines generic: ======= -engines +Engines ======= .. sidebar:: Further reading .. @@ -22,9 +22,11 @@ Shortcut **S** Language support **L** Timeout **TO** Time range support **TR** Disabled **D** Offline **O** ------------- ----------- -------------------- ------------ -Suspend end **SE** -------------- ----------- --------------------------------- Safe search **SS** +------------- ----------- --------------------------------- +Weigth **W** +------------- ----------- --------------------------------- +Disabled **D** ============= =========== ================================= Configuration defaults (at built time): @@ -48,7 +50,8 @@ Configuration defaults (at built time): - D - TR - O - - SE + - W + - D {% for name, mod in engines.items() %} @@ -63,6 +66,7 @@ Configuration defaults (at built time): - {{(mod.disabled and "y") or ""}} - {{(mod.time_range_support and "y") or ""}} - {{(mod.offline and "y") or ""}} - - {{mod.suspend_end_time}} + - {{mod.weight or 1 }} + - {{(mod.disabled and "y") or ""}} {% endfor %} -- cgit v1.2.3 From f9be534b2a480662800b01a7b1e37fa8e3b8a3b3 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 30 Dec 2019 21:55:15 +0100 Subject: docs(dev): fix minor markup typos Signed-off-by: Markus Heiser --- docs/dev/search_api.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 8ca804b8c..13ae6f1ba 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -33,48 +33,48 @@ Parameters ``categories`` : optional Comma separated list, specifies the active search categories -``engines``: optional +``engines`` : optional Comma separated list, specifies the active search engines. -``lang``: default ``all`` +``lang`` : default ``all`` Code of the language. -``pageno``: default ``1`` +``pageno`` : default ``1`` Search page number. -``time_range``: optional +``time_range`` : optional [ ``day``, ``month``, ``year`` ] Time range of search for engines which support it. See if an engine supports time range search in the preferences page of an instance. -``format``: optional +``format`` : optional [ ``json``, ``csv``, ``rss`` ] Output format of results. -``results_on_new_tab``: default ``0`` +``results_on_new_tab`` : default ``0`` [ ``0``, ``1`` ] Open search results on new tab. -``image_proxy``: default ``False`` +``image_proxy`` : default ``False`` [ ``True``, ``False`` ] Proxy image results through searx. -``autocomplete``: default *empty* +``autocomplete`` : default *empty* [ ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` ] Service which completes words as you type. -``safesearch``: default ``None`` +``safesearch`` : default ``None`` [ ``0``, ``1``, ``None`` ] Filter search results of engines which support safe search. See if an engine supports safe search in the preferences page of an instance. -``theme``: default ``oscar`` +``theme`` : default ``oscar`` [ ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` ] Theme of instance. @@ -83,7 +83,7 @@ Parameters instance administrator deleted, created or renamed themes on his/her instance. See the available options in the preferences page of the instance. -``oscar-style``: default ``logicodev`` +``oscar-style`` : default ``logicodev`` [ ``pointhi``, ``logicodev`` ] Style of Oscar theme. It is only parsed if the theme of an instance is @@ -93,7 +93,7 @@ Parameters instance administrator deleted, created or renamed styles on his/her instance. See the available options in the preferences page of the instance. -``enabled_plugins``: optional +``enabled_plugins`` : optional List of enabled plugins. :default: ``HTTPS_rewrite``, ``Self_Informations``, @@ -111,9 +111,9 @@ Parameters ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select`` -``enabled_engines``: optional : *all* :origin:`engines ` +``enabled_engines`` : optional : *all* :origin:`engines ` List of enabled engines. -``disabled_engines``: optional : *all* :origin:`engines ` +``disabled_engines`` : optional : *all* :origin:`engines ` List of disabled engines. -- cgit v1.2.3 From f602cb8e4dde214d51216fb547eb4dfdee32e191 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 30 Dec 2019 21:56:09 +0100 Subject: docs(admin): moved settings description from wiki to docs Move wiki entry https://github.com/asciimoo/searx/wiki/settings.yml into admin section of the docs (#1785). Signed-off-by: Markus Heiser --- docs/admin/engines.rst | 3 +- docs/admin/index.rst | 1 + docs/admin/settings.rst | 181 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/dev/search_api.rst | 7 +- 4 files changed, 187 insertions(+), 5 deletions(-) create mode 100644 docs/admin/settings.rst (limited to 'docs') diff --git a/docs/admin/engines.rst b/docs/admin/engines.rst index c1c69bb0b..4b78c8c2b 100644 --- a/docs/admin/engines.rst +++ b/docs/admin/engines.rst @@ -6,8 +6,7 @@ Engines .. sidebar:: Further reading .. - - :ref:`engines generic` - - :ref:`configured engines` + - :ref:`settings engine` - :ref:`engine settings` - :ref:`engine file` diff --git a/docs/admin/index.rst b/docs/admin/index.rst index 7799343be..b3c7f5119 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -6,6 +6,7 @@ Administrator documentation :maxdepth: 1 installation + settings api architecture filtron diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst new file mode 100644 index 000000000..0bfdcc6cb --- /dev/null +++ b/docs/admin/settings.rst @@ -0,0 +1,181 @@ +.. _settings.yml: + +================ +``settings.yml`` +================ + +.. sidebar:: Further reading .. + + - :ref:`search API` + +This page describe the options possibilities of the settings.yml file. + +.. _settings global: + +Global Settings +=============== + +.. code:: yaml + + server: + port : 8888 + secret_key : "ultrasecretkey" # change this! + debug : False # debug mode, only for development + request_timeout : 2.0 # seconds + base_url : False # set custom base_url (or False) + themes_path : "" # custom ui themes path + default_theme : oscar # ui theme + useragent_suffix : "" # suffix of searx_useragent, could contain + # informations like admins email address + image_proxy : False # proxying image results through searx + default_locale : "" # default interface locale + + # uncomment below section if you want to use a proxy + + #outgoing_proxies : + # http : http://127.0.0.1:8080 + # https: http://127.0.0.1:8080 + + # uncomment below section only if you have more than one network interface + # which can be the source of outgoing search requests + + #source_ips: + # - 1.1.1.1 + # - 1.1.1.2 + + locales: + en : English + de : Deutsch + he : Hebrew + hu : Magyar + fr : Français + es : Español + it : Italiano + nl : Nederlands + ja : 日本語 (Japanese) + tr : Türkçe + ru : Russian + ro : Romanian + + +``port`` : + Port number of the searx web application if you run it directly using ``python + searx/webapp.py``. Doesn't apply to searx running on Apache or Nginx. + +``secret_key`` : + Used for cryptography purpose. + +``debug`` : + Allow a more detailed log if you run searx directly. Display *detailed* error + messages in the browser too, so this must be deactivated in production. + +``request_timeout`` : + Global timeout of the requests made to others engines in seconds. A bigger + timeout will allow to wait for answers from slow engines, but in consequence + will slow searx reactivity (the result page may take the time specified in the + timeout to load) + +``base_url`` : + The base URL where searx is deployed. Used to create correct inbound links. + +``themes_path`` : + Path to where the themes are located. If you didn't develop anything, leave it + blank. + +``default_theme`` : + Name of the theme you want to use by default on you searx instance. + +``useragent_suffix`` : + Suffix to the user-agent searx uses to send requests to others engines. If an + engine wish to block you, a contact info here may be useful to avoid that. + +``image_proxy`` : + Allow your instance of searx of being able to proxy images. Uses memory space. + +``default_locale`` : + Aearx interface language. If blank, the locale is detected by using the + browser language. If it doesn't work, or you are deploying a language + specific instance of searx, a locale can be defined using an ISO language + code, like ``fr``, ``en``, ``de``. + +.. _requests proxies: http://docs.python-requests.org/en/latest/user/advanced/#proxies +.. _PR SOCKS support: https://github.com/kennethreitz/requests/pull/478 + +``outgoing_proxies`` : + Define a proxy you wish to use, see `requests proxies`_. SOCKS proxies are + not supported / see `PR SOCKS support`. + +``source_ips`` : + If you use multiple nework interfaces, define from which IP the requests must + be made. + +``locales`` : + Locales codes and their names. Available translations of searx interface. + + +.. _settings engine: + +Engine settings +=============== + +.. sidebar:: Further reading .. + + - :ref:`engines-dev` + +.. code:: yaml + + - name : bing + engine : bing + shortcut : bi + base_url : 'https://{language}.wikipedia.org/' + categories : general + timeout : 3.0 + api_key : 'apikey' + disabled : True + language : en_US + +``name`` : + Name that will be used accross searx to define this engine. In settings, on + the result page... + +``engine`` : + Name of the python file used to handle requests and responses to and from this + search engine. + +``shortcut`` : + Code used to execute bang requests (in this case using ``!bi`` or ``?bi``) + +``base_url`` : optional + Part of the URL that should be stable accross every request. Can be useful to + use multiple sites using only one engine, or updating the site URL without + touching at the code. + +``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. + +``timeout`` : optional + Timeout of the search with the current search engine. **Be careful, it will + modify the global timeout of searx.** + +``api_key`` : optional + In a few cases, using an API needs the use of a secret key. How to obtain them + is described in the file. + +``disabled`` : optional + To disable by default the engine, but not deleting it. It will allow the user + to manually activate it in the settings. + +``language`` : optional + If you want to use another language for a specific engine, you can define it + by using the full ISO code of language and country, like ``fr_FR``, ``en_US``, + ``de_DE``. + +``weigth`` : default ``1`` + Weighting of the results of this engine. + +.. note:: + + A few more options are possible, but they are pretty specific to some + engines, and so won't be described here. diff --git a/docs/dev/search_api.rst b/docs/dev/search_api.rst index 13ae6f1ba..922548ffb 100644 --- a/docs/dev/search_api.rst +++ b/docs/dev/search_api.rst @@ -1,3 +1,5 @@ +.. _search API: + ========== Search API ========== @@ -16,10 +18,9 @@ Parameters .. sidebar:: Further reading .. + - :ref:`engines-dev` + - :ref:`settings.yml` - :ref:`engines generic` - - :ref:`configured engines` - - :ref:`engine settings` - - :ref:`engine file` ``q`` : required The search query. This string is passed to external search services. Thus, -- cgit v1.2.3 From a1d9c81915b169272cf26139445f3e08e9b689b9 Mon Sep 17 00:00:00 2001 From: Robin Schneider Date: Tue, 31 Dec 2019 14:24:27 +0100 Subject: Fix Nginx subdir URL install docs which allowed download of settings.yml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes: #1617 There is an issue with the setup example in https://asciimoo.github.io/searx/dev/install/installation.html#installation for subdirectory URL deployments: ```nginx root /usr/local/searx; location = /searx { rewrite ^ /searx/; } try_files $uri @searx; } location @searx { uwsgi_param SCRIPT_NAME /searx; include uwsgi_params; uwsgi_modifier1 30; uwsgi_pass unix:/run/uwsgi/app/searx/socket; } ``` `try_files` causes Nginx to search for files in the server root first. If it matches a file, it is returned. Only if no file matched, the request is passed to uwsgi. The worst consequence I can think of is that `settings.yml` can be downloaded without authentication (where secrets and configuration details are stored). To fix this, I propose: ```nginx location = /searx { rewrite ^ /searx/; } location /searx/static { } location /searx { uwsgi_param SCRIPT_NAME /searx; include uwsgi_params; uwsgi_pass unix:/run/uwsgi/app/searx/socket; } ``` And add ``` route-run = fixpathinfo: ``` to `/etc/uwsgi/apps-available/searx.ini` because `uwsgi_modifier1 30` is apparently deprecated. Ref: https://uwsgi-docs.readthedocs.io/en/latest/Changelog-2.0.11.html#fixpathinfo-routing-action I assume this issue exists because some uwsgi upstream docs also use the `try_files` construct (at least I have seen this somewhere in the docs or somewhere else on the Internet but cannot find it right now again). https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html#hosting-multiple-apps-in-the-same-process-aka-managing-script-name-and-path-info also warns about this: > If used incorrectly a configuration like this may cause security problems. For your sanity’s sake, double-triple-quadruple check that your application files, configuration files and any other sensitive files are outside of the root of the static files. --- docs/admin/installation.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst index 239ce0704..28a6b0614 100644 --- a/docs/admin/installation.rst +++ b/docs/admin/installation.rst @@ -114,6 +114,9 @@ content: # Module to import module = searx.webapp + # Support running the module from a webserver subdirectory. + route-run = fixpathinfo: + # Virtualenv and python path virtualenv = /usr/local/searx/searx-ve/ pythonpath = /usr/local/searx/ @@ -180,14 +183,16 @@ Add this configuration in the server config file .. code:: nginx - location = /searx { rewrite ^ /searx/; } - location /searx { - try_files $uri @searx; + location = /searx { + rewrite ^ /searx/; + } + + location /searx/static { } - location @searx { + + location /searx { uwsgi_param SCRIPT_NAME /searx; include uwsgi_params; - uwsgi_modifier1 30; uwsgi_pass unix:/run/uwsgi/app/searx/socket; } @@ -338,4 +343,3 @@ References * How to: `Setup searx in a couple of hours with a free SSL certificate `__ - -- cgit v1.2.3 From 088337295aaeebf8a37d6b4e859cd59019cd3d27 Mon Sep 17 00:00:00 2001 From: Robin Schneider Date: Tue, 31 Dec 2019 14:37:01 +0100 Subject: Simply Nginx example by using alias directive for subdirectory URL We explicitly specific the static directory here using alias to allow to host from a other subdirectory than "searx" which just so happens to match the source code directory. --- docs/admin/installation.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst index 28a6b0614..e0b3779fa 100644 --- a/docs/admin/installation.rst +++ b/docs/admin/installation.rst @@ -183,11 +183,8 @@ Add this configuration in the server config file .. code:: nginx - location = /searx { - rewrite ^ /searx/; - } - location /searx/static { + alias /usr/local/searx/searx/static; } location /searx { -- cgit v1.2.3 From 3e5a3ee4e49c739fdc464d47252c684a42620d48 Mon Sep 17 00:00:00 2001 From: Robin Schneider Date: Tue, 31 Dec 2019 14:38:30 +0100 Subject: Let Nginx deliver static files directory in all examples --- docs/admin/installation.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst index e0b3779fa..15800fc01 100644 --- a/docs/admin/installation.rst +++ b/docs/admin/installation.rst @@ -154,7 +154,10 @@ content: server { listen 80; server_name searx.example.com; - root /usr/local/searx; + root /usr/local/searx/searx; + + location /static { + } location / { include uwsgi_params; @@ -199,6 +202,10 @@ in case of single-user or low-traffic instances.) .. code:: nginx + location /searx/static { + alias /usr/local/searx/searx/static; + } + location /searx { proxy_pass http://127.0.0.1:8888; proxy_set_header Host $host; -- cgit v1.2.3 From 7347d9b508b6003f8407cf1167b677b02a9d0b50 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 4 Jan 2020 17:09:11 +0100 Subject: docs(user): move wiki/Searx-instances from wiki to docs Move wiki entry https://github.com/asciimoo/searx/wiki/Searx-instances into user section of the docs (#1785). Signed-off-by: Markus Heiser --- docs/user/index.rst | 1 + docs/user/public_instances.rst | 257 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 258 insertions(+) create mode 100644 docs/user/public_instances.rst (limited to 'docs') diff --git a/docs/user/index.rst b/docs/user/index.rst index b13aca216..329be3b10 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -5,5 +5,6 @@ User documentation .. toctree:: :maxdepth: 1 + public_instances search_syntax own-instance diff --git a/docs/user/public_instances.rst b/docs/user/public_instances.rst new file mode 100644 index 000000000..c7fb14412 --- /dev/null +++ b/docs/user/public_instances.rst @@ -0,0 +1,257 @@ +.. _public instances: + +====================== +Public Searx instances +====================== + +Useful information +================== + +* Up-to-date health report available on https://stats.searx.xyz(1), for onion (tor) services: https://stats.searx.xyz/tor.html +* Searx instances [mailing list](mailto:searx-instances@autistici.org) & [subscription page](https://www.autistici.org/mailman/listinfo/searx-instances). +* Some of the Searx instances have a CAcert SSL certificate. You can install the missing root cert [from here](http://www.cacert.org/index.php?id=3). +* You can add your own Searx instance to this page by clicking [here](https://github.com/asciimoo/searx/wiki/Searx-instances/_edit) or by clicking on the "Edit" button in the top right corner (when logged in). A GitHub account is required to make changes. + +(1) Note that most of the instances with a A+ grade in CSP column in this site are not fully functional - for example auto-completion may not work. + +List of public Searx instances +============================== + +Meta-searx instances +==================== + +These are websites that source from other searx instances. These are useful if +you can't decide which Searx instance to use: + +| clearnet host | onion host | issuer | source selection method | extra privacy features | +|--|--|--|--|-- +[Neocities](https://searx.neocities.org/) | n/a | Comodo ([verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.neocities.org)) | Redirects users directly to a random selection of any known running server after entering query. Requires Javascript. [Changelog](https://searx.neocities.org/changelog.html). | Excludes servers with user tracking and analytics or are proxied through Cloudflare. | + +Alive and running +================= + +**NOTE:** Public instances listed here may yield less accurate results as they have much higher traffic and consequently have a higher chance of being blocked by search providers such as Google, Qwant, Bing, Startpage, etc. Hosting your own instance or using an instance that isn't listed here may give you a more consistent search experience. + +**BEFORE EDITING**: Please add your Searx instance by respecting the alphabetic order. + +* [**ai.deafpray.wtf/searx**](https://ai.deafpray.wtf/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=ai.deafpray.wtf/searx) +* [**bamboozle.it**](https://bamboozle.it/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=bamboozle.it) +* [**bee.jaekr.dev**](https://bee.jaekr.dev) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=bee.jaekr.dev) +* [**beezboo.com**](https://beezboo.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=beezboo.com) +* [**burtrum.org/searx**](https://burtrum.org/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=burtrum.org/searx) +* [**darmarit.cloud/searx**](https://darmarit.cloud/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=darmarit.cloud/searx) +* [**dc.ax**](https://dc.ax) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=dc.ax) +* [**dynabyte.ca**](https://dynabyte.ca) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=dynabyte.ca) +* [**goso.ga**](https://goso.ga/search) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=goso.ga) +* [**gruble.de**](https://www.gruble.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.gruble.de) +* [**haku.ahmia.fi**](https://haku.ahmia.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.ahmia.fi&latest) +* [**haku.lelux.fi**](https://haku.lelux.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.lelux.fi) +* [**huyo.me**](https://huyo.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=huyo.me) +* [**jsearch.pw**](https://jsearch.pw) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=jsearch.pw) +* [**le-dahut.com/searx**](https://le-dahut.com/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=le-dahut.com/searx) +* [**mijisou.com**](https://mijisou.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=mijisou.com) +* [**null.media**](https://null.media) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=null.media) +* [**openworlds.info**](https://openworlds.info/) - Issuer: Let's Encrypt +* [**perfectpixel.de/searx/**](https://www.perfectpixel.de/searx/) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.perfectpixel.de) +* [**ransack.i2p**](http://ransack.i2p/) - I2P eepsite, only accessible with [I2P](https://geti2p.net/) ([base32 address](http://mqamk4cfykdvhw5kjez2gnvse56gmnqxn7vkvvbuor4k4j2lbbnq.b32.i2p)) +* [**rapu.nz**](https://rapu.nz/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=rapu.nz) +* [**roflcopter.fr**](https://wtf.roflcopter.fr/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=wtf.roflcopter.fr) +* [**roteserver.de/searx**](https://roteserver.de/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=roteserver.de) +* [**s.cmd.gg**](https://s.cmd.gg) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.cmd.gg) +* [**search.activemail.de**](https://search.activemail.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.activemail.de&latest) +* [**search.anonymize.com**](https://search.anonymize.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.anonymize.com) +* [**search.azkware.net**](https://search.azkware.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.azkware.net) +* [**search.biboumail.fr**](https://search.biboumail.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.biboumail.fr) +* [**search.blankenberg.eu**](https://search.blankenberg.eu) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.blankenberg.eu) +* [**search.d4networks.com**](https://search.d4networks.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.d4networks.com) +* [**search.datensturm.net**](https://search.datensturm.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.datensturm.net) +* [**search.disroot.org**](https://search.disroot.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.disroot.org) +* [**search.ethibox.fr**](https://search.ethibox.fr) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.ethibox.fr) +* [**search.fossdaily.xyz**](https://search.fossdaily.xyz) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.fossdaily.xyz) +* [**search.galaxy.cat**](https://search.galaxy.cat) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.galaxy.cat) +* [**search.gibberfish.org**](https://search.gibberfish.org/) (as [Hidden Service](http://o2jdk5mdsijm2b7l.onion/) or [Proxied through Tor](https://search.gibberfish.org/tor/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.gibberfish.org) +* [**search.koehn.com**](https://search.koehn.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.koehn.com) +* [**search.lgbtq.cool**](https://search.lgbtq.cool/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.lgbtq.cool) +* [**search.mdosch.de**](https://search.mdosch.de/) (as [Hidden Service](http://search.4bkxscubgtxwvhpe.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mdosch.de) +* [**search.modalogi.com**](https://search.modalogi.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.modalogi.com&latest) +* [**search.moravit.com**](https://search.moravit.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.moravit.com) +* [**search.nebulacentre.net**](https://search.nebulacentre.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.nebulacentre.net) +* [**search.paulla.asso.fr**](https://search.paulla.asso.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.paulla.asso.fr) +* [**search.pifferi.info**](https://search.pifferi.info/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.pifferi.info&latest) +* [**search.poal.co**](https://search.poal.co/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.poal.co) +* [**search.privacytools.io**](https://search.privacytools.io/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.privacytools.io) - Uses Matomo for user tracking and analytics +* [**search.seds.nl**](https://search.seds.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.seds.nl&latest) +* [**search.snopyta.org**](https://search.snopyta.org/) (as [Hidden Service](http://juy4e6eicawzdrz7.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.snopyta.org) +* [**search.spaeth.me**](https://search.spaeth.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.spaeth.me&latest) +* [**search.st8.at**](https://search.st8.at/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.st8.at) +* [**search.stinpriza.org**](https://search.stinpriza.org) (as [Hidden Service](http://z5vawdol25vrmorm4yydmohsd4u6rdoj2sylvoi3e3nqvxkvpqul7bqd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.stinpriza.org&hideResults=on) +* [**search.sudo-i.net**](https://search.sudo-i.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.sudo-i.net) +* [**search.tolstoevsky.ml**](https://search.tolstoevsky.ml) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.tolstoevsky.ml) +* [**searchsin.com/searx**](https://searchsin.com/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searchsin.com/searx) +* [**searx.anongoth.pl**](https://searx.anongoth.pl) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.anongoth.pl&latest) +* [**searx.be**](https://searx.be) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.be) - Uses Fathom Analytics for user tracking and analytics +* [**searx.ca**](https://searx.ca/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ca) +* [**searx.canox.net**](https://searx.canox.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.canox.net) +* [**searx.cybt.de**](https://searx.cybt.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.cybt.de) +* [**searx.de**](https://www.searx.de/) - Issuer: COMODO [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.de) +* [**searx.decatec.de**](https://searx.decatec.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.decatec.de) +* [**searx.devol.it**](https://searx.devol.it/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=sears.devol.it) +* [**searx.dnswarden.com**](https://searx.dnswarden.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dnswarden.com) +* [**searx.drakonix.net**](https://searx.drakonix.net/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.drakonix.net) +* [**searx.dresden.network**](https://searx.dresden.network/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dresden.network) +* [**searx.elukerio.org**](https://searx.elukerio.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.elukerio.org/) +* [**searx.everdot.org**](https://searx.everdot.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.everdot.org/) - Crawls using YaCy +* [**searx.foo.li**](https://searx.foo.li) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.foo.li&hideResults=on) +* [**searx.fossencdi.org**](https://searx.fossencdi.org) (as [Hidden Service](http://searx.cwuzdtzlubq5uual.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.fossencdi.org) +* [**searx.fr32k.de**](https://searx.fr32k.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.fr32k.de) +* [**searx.good.one.pl**](https://searx.good.one.pl) (as [Hidden Service](http://searxl7u2y6gvonm.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.good.one.pl) +* [**searx.gotrust.de**](https://searx.gotrust.de/) (as [Hidden Service](http://nxhhwbbxc4khvvlw.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.gotrust.de) +* [**searx.hardwired.link**](https://searx.hardwired.link/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.hardwired.link) +* [**searx.hlfh.space**](https://searx.hlfh.space) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.hlfh.space) +* [**searx.info**](https://searx.info) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.info) +* [**searx.itunix.eu**](https://searx.itunix.eu/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.itunix.eu) +* [**searx.john-at-me.net**](https://searx.john-at-me.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.john-at-me.net) +* [**searx.kvch.me**](https://searx.kvch.me) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.kvch.me) +* [**searx.laquadrature.net**](https://searx.laquadrature.net) (as [Hidden Service](http://searchb5a7tmimez.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.laquadrature.net) +* [**searx.lelux.fi**](https://searx.lelux.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.lelux.fi) +* [**searx.lhorn.de**](https://searx.lhorn.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lhorn.de&latest) +* [**searx.li**](https://searx.li/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.li) +* [**searx.libmail.eu**](https://searx.libmail.eu/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.libmail.eu/) +* [**searx.linux.pizza**](https://searx.linux.pizza) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.linux.pizza) +* [**searx.lynnesbian.space**](https://searx.lynnesbian.space/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lynnesbian.space) +* [**searx.mastodontech.de**](https://searx.mastodontech.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mastodontech.de) +* [**searx.me**](https://searx.me) (as [Hidden Service](http://ulrn6sryqaifefld.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.me) +* [**searx.mxchange.org**](https://searx.mxchange.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mxchange.org) +* [**searx.nakhan.net**](https://searx.nakhan.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nakhan.net) +* [**searx.nixnet.xyz**](https://searx.nixnet.xyz) (as [Hidden Service](http://searx.l4qlywnpwqsluw65ts7md3khrivpirse744un3x7mlskqauz5pyuzgqd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nixnet.xyz) +* [**searx.nnto.net**](https://searx.nnto.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nnto.net) +* [**searx.openhoofd.nl**](https://searx.openhoofd.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=openhoofd.nl) +* [**searx.openpandora.org**](https://searx.openpandora.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.openpandora.org&latest) +* [**searx.operationtulip.com**](https://searx.operationtulip.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.operationtulip.com) +* [**searx.orcadian.net**](https://searx.orcadian.net/) - Issuer: Comodo CA Limited [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.orcadian.net) +* [**searx.ouahpit.info**](https://searx.ouahpiti.info/) - Issuer: Let's Encrypt +* [**searx.pofilo.fr**](https://searx.pofilo.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.pofilo.fr) +* [**searx.prvcy.eu**](https://searx.prvcy.eu/) (as [Hidden Service](http://hmfztxt3pfhevucl.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.prvcy.eu) +* [**searx.pwoss.org**](https://searx.pwoss.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.pwoss.org) +* [**searx.ro**](https://searx.ro/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ro) +* [**searx.ru**](https://searx.ru/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ru) +* [**searx.solusar.de**](https://searx.solusar.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.solusar.de) +* [**searx.targaryen.house**](https://searx.targaryen.house/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.targaryen.house) +* [**searx.tuxcloud.net**](https://searx.tuxcloud.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.tuxcloud.net) +* [**searx.tyil.nl**](https://searx.tyil.nl) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.tyil.nl) +* [**searx.wegeeks.win**](https://searx.wegeeks.win) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.wegeeks.win) +* [**searx.win**](https://searx.win/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.win&latest) +* [**searx.xyz**](https://searx.xyz/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.xyz&latest) +* [**searx.zareldyn.net**](https://searx.zareldyn.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.zareldyn.net) +* [**searx.zdechov.net**](https://searx.zdechov.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.zdechov.net) +* [**searxes.eu.org**](https://searxes.eu.org) ([As Hidden Service](http://searxes.nmqnkngye4ct7bgss4bmv5ca3wpa55yugvxen5kz2bbq67lwy6ps54yd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searxes.eu.org) +* [**searxs.eu**](https://www.searxs.eu) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.searxs.eu&hideResults=on) +* [**seeks.hsbp.org**](https://seeks.hsbp.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=seeks.hsbp.org) - [PGP signed fingerprints of cert](https://seeks.hsbp.org/cert) +* [**skyn3t.in/srx**](https://skyn3t.in/srx/) - Issuer: Let's Encrypt | onion [hidden service](http://skyn3tb3bas655mw.onion/srx/) +* [**spot.ecloud.global**](https://spot.ecloud.global/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=spot.ecloud.global) +* [**srx.sx**](https://srx.sx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=srx.sx) +* [**stemy.me/searx**](https://stemy.me/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=stemy.me) +* [**suche.dasnetzundich.de**](https://suche.dasnetzundich.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.dasnetzundich.de) +* [**suche.elaon.de**](https://suche.elaon.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.elaon.de) +* [**suche.xyzco456vwisukfg.onion**](http://suche.xyzco456vwisukfg.onion/) +* [**suche.uferwerk.org**](https://suche.uferwerk.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.uferwerk.org) +* [**timdor.noip.me/searx**](https://timdor.noip.me/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=timdor.noip.me/searx) +* [**trovu.komun.org**](https://trovu.komun.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=trovu.komun.org) +* [**unmonito.red**](https://unmonito.red/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=unmonito.red) +* [**www.finden.tk**](https://www.finden.tk/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.finden.tk) +* [**zoek.anchel.nl**](https://zoek.anchel.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=zoek.anchel.nl) + +Running in exclusive private walled-gardens +=========================================== + +These instances run in walled-gardens that exclude some segment of the general public (e.g. Tor users and users sharing IPs with many other users). Caution: privacy is also compromised on these sites due to exposure of cleartext traffic to a third party other than the website operator. +* [**intelme.com**](https://intelme.com) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=intelme.com) +* [**search404.io**](https://www.search404.io/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search404.io) +* [**searx.com.au**](https://searx.com.au/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.com.au) +* [**searx.lavatech.top**](https://searx.lavatech.top/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lavatech.top) +* [**searchx.mobi**](https://searchx.mobi/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searchx.mobi) +* [**searx.org**](https://searx.org/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.org) +* [**searx.run**](https://searx.run/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.run) +* [**searx.world**](https://searx.world) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.world) - Adds Amazon affiliate links + +Running with an incorrect SSL certificate +========================================= + +* [**listi.me**](https://listi.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=listi.me&latest) +* [**s.matejc.com**](https://s.matejc.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.matejc.com) +* [**search.jollausers.de**](https://search.jollausers.de) - Incorrectly configured [SSL certificate](https://www.ssllabs.com/ssltest/analyze.html?d=search.jollausers.de) +* [**search.paviro.de**](https://search.paviro.de) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.paviro.de) +* [**searx.abenthung.it**](https://searx.abenthung.it/) - Issuer: Comodo CA Limited [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.abenthung.it) +* [**searx.coding4schoki.org**](https://searx.coding4schoki.org/) - Incorrectly configured [SSL Certificate](https://www.ssllabs.com/ssltest/analyze.html?d=searx.coding4schoki.org) +* [**searx.haxors.club**](https://searx.haxors.club/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.haxors.club) +* [**searx.nulltime.net**](https://searx.nulltime.net/) (as [Hidden Service](http://searx7gwtu5rh6wr.onion)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nulltime.net) +* [**searx.ch**](https://searx.ch/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ch) (cert clock problems) + +Offline +======= + +* [**a.searx.space**](https://a.searx.space) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=a.searx.space) (unstable, under construction). +* [**anyonething.de**](https://anyonething.de) - (was found to have become a pastebin on or before 2019-03-01) Issuer: Comodo CA Limited (Warning: uses Cloudflare) [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=anyonething.de) +* [**h7jwxg5rakyfvikpi.onion**](http://7jwxg5rakyfvikpi.onion/) - available only as Tor Hidden Service (down on 2019-06-26) +* [**hacktivis.me/searx**](https://hacktivis.me/searx) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=hacktivis.me/searx) +* [**icebal.com**](https://icebal.com) - (down) Issuer: Let's Encrypt +* [**netrangler.host**](https://netrangler.host) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=netrangler.host) +* [**opengo.nl**](https://www.opengo.nl) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.opengo.nl) +* [**p9e.de**](https://p9e.de/) - (down - timeout) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=p9e.de) +* [**rubri.co**](https://rubri.co) - (down) Issuer: Let's Encrypt +* [**s.bacafe.xyz**](https://s.bacafe.xyz/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.bacafe.xyz&latest) +* [**search.alecpap.com**](https://search.alecpap.com/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.alecpap.com) +* [**search.blackit.de**](https://search.blackit.de/) - (down) Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.blackit.de) +* [**search.deblan.org**](https://search.deblan.org/) (down) - Issuer: COMODO via GANDI [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.deblan.org) +* [**search.homecomputing.fr**](https://search.homecomputing.fr/) - (down) Issuer: CAcert [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.homecomputing.fr) +* [**search.jpope.org**](https://search.jpope.org) - (down - timeout) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.jpope.org) +* [**search.kakise.xyz**](https://search.kakise.xyz/) - down +* [**search.kosebamse.com**](https://search.kosebamse.com) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.kosebamse.com) +* [**search.kujiu.org**](https://search.kujiu.org) - (down) Issuer: Let's Encrypt +* [**search.mailaender.coffee**](https://search.mailaender.coffee/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mailaender.coffee) +* [**search.matrix.ac**](https://search.matrix.ac) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=matrix.ac) +* [**search.mypsc.ca**](https://search.mypsc.ca/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mypsc.ca) +* [**search.namedkitten.pw**](https://search.namedkitten.pw) - (SSL error) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.namedkitten.pw) +* [**search.opentunisia.org**](https://search.opentunisia.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.opentunisia.org) +* [**search.r3d007.com**](https://search.r3d007.com/) - (down) Issuer: Let's Encrypt +* [**search.static.lu**](https://search.static.lu/) - (down) Issuer: StartCom [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.static.lu) +* [**search.teej.xyz**](https://search.teej.xyz) - (down) Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.teej.xyz) +* [**search.wxzm.sx**](https://search.wxzm.sx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.wxzm.sx) +* [**searx.4ray.co**](https://searx.4ray.co/) - (no longer an instance, redirects to main page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.4ray.co) +* [**searx.32bitflo.at**](https://searx.32bitflo.at/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.32bitflo.at) +* [**searx.ahh.si**](https://searx.ahh.si/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ahh.si) +* [**searx.angristan.xyz**](https://searx.angristan.xyz/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.angristan.xyz) +* [**searx.antirep.net**](https://searx.antirep.net/) - (return a 502 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.antirep.net) +* [**searx.aquilenet.fr**](https://searx.aquilenet.fr/) - (down - 429 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.aquilenet.fr) +* [**searx.at**](https://searx.at/) - (return "request exception" at every search) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.at) +* [**searx.cc**](https://searx.cc/) - (down on 2019-06-26) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.cc) +* [**searx.dk**](https://searx.dk/) - (down - 429 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dk) +* [**searx.ehrmanns.ch**](https://searx.ehrmanns.ch) - (down) Issuer: Let's Encrypt +* [**searx.glibre.net**](https://searx.glibre.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.glibre.net) +* [**searx.infini.fr**](https://searx.infini.fr) - (return a page stating that the website is not installed) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.infini.fr) +* [**searx.jeanphilippemorvan.info**](https://searx.jeanphilippemorvan.info/) - (down) Issuer: StartCom [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.jeanphilippemorvan.info) +* [**searx.lhorn.de**](https://searx.lhorn.de/) - (redirect the Searx's github repository page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lhorn.de&latest) (only reachable from european countries) +* [**searx.lvweb.host**](https://searx.lvweb.host) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lvweb.host) +* [**searx.mrtino.eu**](https://searx.mrtino.eu) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mrtino.eu) +* [**searx.netzspielplatz.de**](https://searx.netzspielplatz.de/) - (error page about GDPR even when browsing it from USA and Asia) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.netzspielplatz.de) +* [**searx.new-admin.net**](https://searx.new-admin.net) - (down) Issuer: Let's Encrypt +* [**searx.nogafa.org**](https://searx.nogafa.org/)- (broken CSS) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nogafa.org) +* [**searx.potato.hu**](https://searx.potato.hu) - (not a searx instance) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.potato.hu) +* [**searx.rubbeldiekatz.info**](https://searx.rubbeldiekatz.info/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.rubbeldiekatz.info/) +* [**searx.s42.space**](https://searx.s42.space) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.s42.space) +* [**searx.salcay.hu**](https://searx.salcay.hu/) - (down - blank page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.salcay.hu) +* [**searx.selea.se**](https://searx.selea.se) - (Leads to default Apache page) Issuer: RapidSSL (HSTS preloaded, DNSSEC) [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.selea.se) | [HSTS Preload](https://hstspreload.org/?domain=searx.selea.se) +* [**searx.steinscraft.net**](https://searx.steinscraft.net/) - (down) Issuer: Cloudflare +* [**searx.techregion.de**](https://searx.techregion.de/) - (domain expired) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.techregion.de) +* [**searx.tognella.com**](https://searx.tognella.com/) - (down) Issuer: Cloudflare +* [**searx.xi.ht**](https://searx.xi.ht/) - (return a 502 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.xi.ht) +* [**searxist.com**](https://searxist.com/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searxist.com) +* [**so.sb**](https://so.sb/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=so.sb) +* [**srx.stdout.net**](https://srx.stdout.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=srx.stdout.net) +* [**w6f7cgdm54cyvohcuhraaafhajctyj3ihenrovuxogoagrr5g43qmoid.onion**](http://w6f7cgdm54cyvohcuhraaafhajctyj3ihenrovuxogoagrr5g43qmoid.onion/) - Hidden Service +* [**win8linux.nohost.me**](https://win8linux.nohost.me/searx/) - (down) Issuer: Let's Encrypt +* [**wiznet.tech**](https://wiznet.tech) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=wiznet.tech) +* [**www.mercurius.space**](https://www.mercurius.space/) - (down) Issuer: Let's Encrypt +* [**www.ready.pm**](https://www.ready.pm) - Issuer: WoSign [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.ready.pm) +* [**z.awsmppl.com**](https://z.awsmppl.com) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=z.awsmppl.com) +* [**zlsdzh.tk**](https://zlsdzh.tk) - (down - 404 HTTP error) Issuer: TrustAsia Technologies, Inc. [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=zlsdzh.tk)* -- cgit v1.2.3 From 200c3a31f50b2e09e8e0192cca175b7e4477d4bf Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 4 Jan 2020 18:26:04 +0100 Subject: docs(user): move wiki/Searx-instances from wiki to docs (WIP) Move wiki entry https://github.com/asciimoo/searx/wiki/Searx-instances into user section of the docs (#1785). links has been ported from markdown to reST by:: regexpr: \[([^\]]*)\]\(([^)]*)\) substitution: `\1 <\2>`__ Signed-off-by: Markus Heiser --- docs/user/public_instances.rst | 464 ++++++++++++++++++++++------------------- 1 file changed, 249 insertions(+), 215 deletions(-) (limited to 'docs') diff --git a/docs/user/public_instances.rst b/docs/user/public_instances.rst index c7fb14412..a88acc479 100644 --- a/docs/user/public_instances.rst +++ b/docs/user/public_instances.rst @@ -1,5 +1,12 @@ .. _public instances: +.. + links has been ported from markdown to reST by:: + + regexpr: \[([^\]]*)\]\(([^)]*)\) + substitution: `\1 <\2>`__ + + ====================== Public Searx instances ====================== @@ -8,9 +15,9 @@ Useful information ================== * Up-to-date health report available on https://stats.searx.xyz(1), for onion (tor) services: https://stats.searx.xyz/tor.html -* Searx instances [mailing list](mailto:searx-instances@autistici.org) & [subscription page](https://www.autistici.org/mailman/listinfo/searx-instances). -* Some of the Searx instances have a CAcert SSL certificate. You can install the missing root cert [from here](http://www.cacert.org/index.php?id=3). -* You can add your own Searx instance to this page by clicking [here](https://github.com/asciimoo/searx/wiki/Searx-instances/_edit) or by clicking on the "Edit" button in the top right corner (when logged in). A GitHub account is required to make changes. +* Searx instances `mailing list `__ & `subscription page `__. +* Some of the Searx instances have a CAcert SSL certificate. You can install the missing root cert `from here `__. +* You can add your own Searx instance to this page by clicking `here `__ or by clicking on the "Edit" button in the top right corner (when logged in). A GitHub account is required to make changes. (1) Note that most of the instances with a A+ grade in CSP column in this site are not fully functional - for example auto-completion may not work. @@ -23,9 +30,27 @@ Meta-searx instances These are websites that source from other searx instances. These are useful if you can't decide which Searx instance to use: -| clearnet host | onion host | issuer | source selection method | extra privacy features | -|--|--|--|--|-- -[Neocities](https://searx.neocities.org/) | n/a | Comodo ([verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.neocities.org)) | Redirects users directly to a random selection of any known running server after entering query. Requires Javascript. [Changelog](https://searx.neocities.org/changelog.html). | Excludes servers with user tracking and analytics or are proxied through Cloudflare. | + +.. flat-table:: Meta-searx instances + :header-rows: 1 + :stub-columns: 0 + :widths: 2 1 2 4 4 + + * - clearnet host + - onion host + - issuer + - source selection method + - extra privacy features + + * - `Neocities `__ + - n/a + - Comodo (`verification `__) + - Redirects users directly to a random selection of any known running + server after entering query. Requires + Javascript. `Changelog `__. + - Excludes servers with user tracking and analytics or are proxied through + Cloudflare. + Alive and running ================= @@ -34,224 +59,233 @@ Alive and running **BEFORE EDITING**: Please add your Searx instance by respecting the alphabetic order. -* [**ai.deafpray.wtf/searx**](https://ai.deafpray.wtf/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=ai.deafpray.wtf/searx) -* [**bamboozle.it**](https://bamboozle.it/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=bamboozle.it) -* [**bee.jaekr.dev**](https://bee.jaekr.dev) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=bee.jaekr.dev) -* [**beezboo.com**](https://beezboo.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=beezboo.com) -* [**burtrum.org/searx**](https://burtrum.org/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=burtrum.org/searx) -* [**darmarit.cloud/searx**](https://darmarit.cloud/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=darmarit.cloud/searx) -* [**dc.ax**](https://dc.ax) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=dc.ax) -* [**dynabyte.ca**](https://dynabyte.ca) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=dynabyte.ca) -* [**goso.ga**](https://goso.ga/search) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=goso.ga) -* [**gruble.de**](https://www.gruble.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.gruble.de) -* [**haku.ahmia.fi**](https://haku.ahmia.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.ahmia.fi&latest) -* [**haku.lelux.fi**](https://haku.lelux.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.lelux.fi) -* [**huyo.me**](https://huyo.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=huyo.me) -* [**jsearch.pw**](https://jsearch.pw) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=jsearch.pw) -* [**le-dahut.com/searx**](https://le-dahut.com/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=le-dahut.com/searx) -* [**mijisou.com**](https://mijisou.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=mijisou.com) -* [**null.media**](https://null.media) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=null.media) -* [**openworlds.info**](https://openworlds.info/) - Issuer: Let's Encrypt -* [**perfectpixel.de/searx/**](https://www.perfectpixel.de/searx/) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.perfectpixel.de) -* [**ransack.i2p**](http://ransack.i2p/) - I2P eepsite, only accessible with [I2P](https://geti2p.net/) ([base32 address](http://mqamk4cfykdvhw5kjez2gnvse56gmnqxn7vkvvbuor4k4j2lbbnq.b32.i2p)) -* [**rapu.nz**](https://rapu.nz/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=rapu.nz) -* [**roflcopter.fr**](https://wtf.roflcopter.fr/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=wtf.roflcopter.fr) -* [**roteserver.de/searx**](https://roteserver.de/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=roteserver.de) -* [**s.cmd.gg**](https://s.cmd.gg) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.cmd.gg) -* [**search.activemail.de**](https://search.activemail.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.activemail.de&latest) -* [**search.anonymize.com**](https://search.anonymize.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.anonymize.com) -* [**search.azkware.net**](https://search.azkware.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.azkware.net) -* [**search.biboumail.fr**](https://search.biboumail.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.biboumail.fr) -* [**search.blankenberg.eu**](https://search.blankenberg.eu) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.blankenberg.eu) -* [**search.d4networks.com**](https://search.d4networks.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.d4networks.com) -* [**search.datensturm.net**](https://search.datensturm.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.datensturm.net) -* [**search.disroot.org**](https://search.disroot.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.disroot.org) -* [**search.ethibox.fr**](https://search.ethibox.fr) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.ethibox.fr) -* [**search.fossdaily.xyz**](https://search.fossdaily.xyz) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.fossdaily.xyz) -* [**search.galaxy.cat**](https://search.galaxy.cat) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.galaxy.cat) -* [**search.gibberfish.org**](https://search.gibberfish.org/) (as [Hidden Service](http://o2jdk5mdsijm2b7l.onion/) or [Proxied through Tor](https://search.gibberfish.org/tor/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.gibberfish.org) -* [**search.koehn.com**](https://search.koehn.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.koehn.com) -* [**search.lgbtq.cool**](https://search.lgbtq.cool/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.lgbtq.cool) -* [**search.mdosch.de**](https://search.mdosch.de/) (as [Hidden Service](http://search.4bkxscubgtxwvhpe.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mdosch.de) -* [**search.modalogi.com**](https://search.modalogi.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.modalogi.com&latest) -* [**search.moravit.com**](https://search.moravit.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.moravit.com) -* [**search.nebulacentre.net**](https://search.nebulacentre.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.nebulacentre.net) -* [**search.paulla.asso.fr**](https://search.paulla.asso.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.paulla.asso.fr) -* [**search.pifferi.info**](https://search.pifferi.info/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.pifferi.info&latest) -* [**search.poal.co**](https://search.poal.co/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.poal.co) -* [**search.privacytools.io**](https://search.privacytools.io/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.privacytools.io) - Uses Matomo for user tracking and analytics -* [**search.seds.nl**](https://search.seds.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.seds.nl&latest) -* [**search.snopyta.org**](https://search.snopyta.org/) (as [Hidden Service](http://juy4e6eicawzdrz7.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.snopyta.org) -* [**search.spaeth.me**](https://search.spaeth.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.spaeth.me&latest) -* [**search.st8.at**](https://search.st8.at/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.st8.at) -* [**search.stinpriza.org**](https://search.stinpriza.org) (as [Hidden Service](http://z5vawdol25vrmorm4yydmohsd4u6rdoj2sylvoi3e3nqvxkvpqul7bqd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.stinpriza.org&hideResults=on) -* [**search.sudo-i.net**](https://search.sudo-i.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.sudo-i.net) -* [**search.tolstoevsky.ml**](https://search.tolstoevsky.ml) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.tolstoevsky.ml) -* [**searchsin.com/searx**](https://searchsin.com/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searchsin.com/searx) -* [**searx.anongoth.pl**](https://searx.anongoth.pl) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.anongoth.pl&latest) -* [**searx.be**](https://searx.be) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.be) - Uses Fathom Analytics for user tracking and analytics -* [**searx.ca**](https://searx.ca/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ca) -* [**searx.canox.net**](https://searx.canox.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.canox.net) -* [**searx.cybt.de**](https://searx.cybt.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.cybt.de) -* [**searx.de**](https://www.searx.de/) - Issuer: COMODO [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.de) -* [**searx.decatec.de**](https://searx.decatec.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.decatec.de) -* [**searx.devol.it**](https://searx.devol.it/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=sears.devol.it) -* [**searx.dnswarden.com**](https://searx.dnswarden.com) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dnswarden.com) -* [**searx.drakonix.net**](https://searx.drakonix.net/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.drakonix.net) -* [**searx.dresden.network**](https://searx.dresden.network/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dresden.network) -* [**searx.elukerio.org**](https://searx.elukerio.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.elukerio.org/) -* [**searx.everdot.org**](https://searx.everdot.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.everdot.org/) - Crawls using YaCy -* [**searx.foo.li**](https://searx.foo.li) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.foo.li&hideResults=on) -* [**searx.fossencdi.org**](https://searx.fossencdi.org) (as [Hidden Service](http://searx.cwuzdtzlubq5uual.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.fossencdi.org) -* [**searx.fr32k.de**](https://searx.fr32k.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.fr32k.de) -* [**searx.good.one.pl**](https://searx.good.one.pl) (as [Hidden Service](http://searxl7u2y6gvonm.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.good.one.pl) -* [**searx.gotrust.de**](https://searx.gotrust.de/) (as [Hidden Service](http://nxhhwbbxc4khvvlw.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.gotrust.de) -* [**searx.hardwired.link**](https://searx.hardwired.link/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.hardwired.link) -* [**searx.hlfh.space**](https://searx.hlfh.space) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.hlfh.space) -* [**searx.info**](https://searx.info) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.info) -* [**searx.itunix.eu**](https://searx.itunix.eu/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.itunix.eu) -* [**searx.john-at-me.net**](https://searx.john-at-me.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.john-at-me.net) -* [**searx.kvch.me**](https://searx.kvch.me) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.kvch.me) -* [**searx.laquadrature.net**](https://searx.laquadrature.net) (as [Hidden Service](http://searchb5a7tmimez.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.laquadrature.net) -* [**searx.lelux.fi**](https://searx.lelux.fi/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=haku.lelux.fi) -* [**searx.lhorn.de**](https://searx.lhorn.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lhorn.de&latest) -* [**searx.li**](https://searx.li/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.li) -* [**searx.libmail.eu**](https://searx.libmail.eu/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.libmail.eu/) -* [**searx.linux.pizza**](https://searx.linux.pizza) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.linux.pizza) -* [**searx.lynnesbian.space**](https://searx.lynnesbian.space/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lynnesbian.space) -* [**searx.mastodontech.de**](https://searx.mastodontech.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mastodontech.de) -* [**searx.me**](https://searx.me) (as [Hidden Service](http://ulrn6sryqaifefld.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.me) -* [**searx.mxchange.org**](https://searx.mxchange.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mxchange.org) -* [**searx.nakhan.net**](https://searx.nakhan.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nakhan.net) -* [**searx.nixnet.xyz**](https://searx.nixnet.xyz) (as [Hidden Service](http://searx.l4qlywnpwqsluw65ts7md3khrivpirse744un3x7mlskqauz5pyuzgqd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nixnet.xyz) -* [**searx.nnto.net**](https://searx.nnto.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nnto.net) -* [**searx.openhoofd.nl**](https://searx.openhoofd.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=openhoofd.nl) -* [**searx.openpandora.org**](https://searx.openpandora.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.openpandora.org&latest) -* [**searx.operationtulip.com**](https://searx.operationtulip.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.operationtulip.com) -* [**searx.orcadian.net**](https://searx.orcadian.net/) - Issuer: Comodo CA Limited [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.orcadian.net) -* [**searx.ouahpit.info**](https://searx.ouahpiti.info/) - Issuer: Let's Encrypt -* [**searx.pofilo.fr**](https://searx.pofilo.fr/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.pofilo.fr) -* [**searx.prvcy.eu**](https://searx.prvcy.eu/) (as [Hidden Service](http://hmfztxt3pfhevucl.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.prvcy.eu) -* [**searx.pwoss.org**](https://searx.pwoss.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.pwoss.org) -* [**searx.ro**](https://searx.ro/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ro) -* [**searx.ru**](https://searx.ru/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ru) -* [**searx.solusar.de**](https://searx.solusar.de/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.solusar.de) -* [**searx.targaryen.house**](https://searx.targaryen.house/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.targaryen.house) -* [**searx.tuxcloud.net**](https://searx.tuxcloud.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.tuxcloud.net) -* [**searx.tyil.nl**](https://searx.tyil.nl) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.tyil.nl) -* [**searx.wegeeks.win**](https://searx.wegeeks.win) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.wegeeks.win) -* [**searx.win**](https://searx.win/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.win&latest) -* [**searx.xyz**](https://searx.xyz/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.xyz&latest) -* [**searx.zareldyn.net**](https://searx.zareldyn.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.zareldyn.net) -* [**searx.zdechov.net**](https://searx.zdechov.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.zdechov.net) -* [**searxes.eu.org**](https://searxes.eu.org) ([As Hidden Service](http://searxes.nmqnkngye4ct7bgss4bmv5ca3wpa55yugvxen5kz2bbq67lwy6ps54yd.onion/)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searxes.eu.org) -* [**searxs.eu**](https://www.searxs.eu) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.searxs.eu&hideResults=on) -* [**seeks.hsbp.org**](https://seeks.hsbp.org/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=seeks.hsbp.org) - [PGP signed fingerprints of cert](https://seeks.hsbp.org/cert) -* [**skyn3t.in/srx**](https://skyn3t.in/srx/) - Issuer: Let's Encrypt | onion [hidden service](http://skyn3tb3bas655mw.onion/srx/) -* [**spot.ecloud.global**](https://spot.ecloud.global/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=spot.ecloud.global) -* [**srx.sx**](https://srx.sx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=srx.sx) -* [**stemy.me/searx**](https://stemy.me/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=stemy.me) -* [**suche.dasnetzundich.de**](https://suche.dasnetzundich.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.dasnetzundich.de) -* [**suche.elaon.de**](https://suche.elaon.de) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.elaon.de) -* [**suche.xyzco456vwisukfg.onion**](http://suche.xyzco456vwisukfg.onion/) -* [**suche.uferwerk.org**](https://suche.uferwerk.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=suche.uferwerk.org) -* [**timdor.noip.me/searx**](https://timdor.noip.me/searx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=timdor.noip.me/searx) -* [**trovu.komun.org**](https://trovu.komun.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=trovu.komun.org) -* [**unmonito.red**](https://unmonito.red/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=unmonito.red) -* [**www.finden.tk**](https://www.finden.tk/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.finden.tk) -* [**zoek.anchel.nl**](https://zoek.anchel.nl/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=zoek.anchel.nl) +* `ai.deafpray.wtf/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `bamboozle.it `__ - Issuer: Let's Encrypt `Verification `__ +* `bee.jaekr.dev `__ - Issuer: Let's Encrypt `Verification `__ +* `beezboo.com `__ - Issuer: Let's Encrypt `Verification `__ +* `burtrum.org/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `darmarit.cloud/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `dc.ax `__ - Issuer: Let's Encrypt `Verification `__ +* `dynabyte.ca `__ - Issuer: Let's Encrypt `Verification `__ +* `goso.ga `__ - Issuer: Let's Encrypt `Verification `__ +* `gruble.de `__ - Issuer: Let's Encrypt `Verification `__ +* `haku.ahmia.fi `__ - Issuer: Let's Encrypt `Verification `__ +* `haku.lelux.fi `__ - Issuer: Let's Encrypt `Verification `__ +* `huyo.me `__ - Issuer: Let's Encrypt `Verification `__ +* `jsearch.pw `__ - Issuer: Let's Encrypt `Verification `__ +* `le-dahut.com/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `mijisou.com `__ - Issuer: Let's Encrypt `Verification `__ +* `null.media `__ - Issuer: Let's Encrypt `Verification `__ +* `openworlds.info `__ - Issuer: Let's Encrypt +* `perfectpixel.de/searx/ `__ - Issuer: LetsEncrypt `Verification `__ +* `ransack.i2p `__ - I2P eepsite, only accessible with `I2P `__ (`base32 address `__) +* `rapu.nz `__ - Issuer: Let's Encrypt `Verification `__ +* `roflcopter.fr `__ - Issuer: Let's Encrypt `Verification `__ +* `roteserver.de/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `s.cmd.gg `__ - Issuer: Let's Encrypt `Verification `__ +* `search.activemail.de `__ - Issuer: Let's Encrypt `Verification `__ +* `search.anonymize.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.azkware.net `__ - Issuer: Let's Encrypt `Verification `__ +* `search.biboumail.fr `__ - Issuer: Let's Encrypt `Verification `__ +* `search.blankenberg.eu `__ - Issuer: Let's Encrypt `Verification `__ +* `search.d4networks.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.datensturm.net `__ - Issuer: Let's Encrypt `Verification `__ +* `search.disroot.org `__ - Issuer: Let's Encrypt `Verification `__ +* `search.ethibox.fr `__ - Issuer: Let's Encrypt `Verification `__ +* `search.fossdaily.xyz `__ - Issuer: Let's Encrypt `Verification `__ +* `search.galaxy.cat `__ - Issuer: Let's Encrypt `Verification `__ +* `search.gibberfish.org `__ (as `Hidden Service `__ or `Proxied through Tor `__) - Issuer: Let's Encrypt `Verification `__ +* `search.koehn.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.lgbtq.cool `__ - Issuer: Let's Encrypt `Verification `__ +* `search.mdosch.de `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `search.modalogi.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.moravit.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.nebulacentre.net `__ - Issuer: Let's Encrypt `Verification `__ +* `search.paulla.asso.fr `__ - Issuer: Let's Encrypt `Verification `__ +* `search.pifferi.info `__ - Issuer: Let's Encrypt `Verification `__ +* `search.poal.co `__ - Issuer: Let's Encrypt `Verification `__ +* `search.privacytools.io `__ - Issuer: Let's Encrypt `Verification `__ - Uses Matomo for user tracking and analytics +* `search.seds.nl `__ - Issuer: Let's Encrypt `Verification `__ +* `search.snopyta.org `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `search.spaeth.me `__ - Issuer: Let's Encrypt `Verification `__ +* `search.st8.at `__ - Issuer: Let's Encrypt `Verification `__ +* `search.stinpriza.org `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `search.sudo-i.net `__ - Issuer: Let's Encrypt `Verification `__ +* `search.tolstoevsky.ml `__ - Issuer: Let's Encrypt `Verification `__ +* `searchsin.com/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.anongoth.pl `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.be `__ - Issuer: Let's Encrypt `Verification `__ - Uses Fathom Analytics for user tracking and analytics +* `searx.ca `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.canox.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.cybt.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.de `__ - Issuer: COMODO `Verification `__ +* `searx.decatec.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.devol.it `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.dnswarden.com `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.drakonix.net `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.dresden.network `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.elukerio.org `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.everdot.org `__ - Issuer: Let's Encrypt `Verification `__ - Crawls using YaCy +* `searx.foo.li `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.fossencdi.org `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.fr32k.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.good.one.pl `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.gotrust.de `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.hardwired.link `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.hlfh.space `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.info `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.itunix.eu `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.john-at-me.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.kvch.me `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.laquadrature.net `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.lelux.fi `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.lhorn.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.li `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.libmail.eu `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.linux.pizza `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.lynnesbian.space `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.mastodontech.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.me `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.mxchange.org `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.nakhan.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.nixnet.xyz `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.nnto.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.openhoofd.nl `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.openpandora.org `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.operationtulip.com `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.orcadian.net `__ - Issuer: Comodo CA Limited `Verification `__ +* `searx.ouahpit.info `__ - Issuer: Let's Encrypt +* `searx.pofilo.fr `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.prvcy.eu `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.pwoss.org `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.ro `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.ru `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.solusar.de `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.targaryen.house `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.tuxcloud.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.tyil.nl `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.wegeeks.win `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.win `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.xyz `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.zareldyn.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.zdechov.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searxes.eu.org `__ (`As Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searxs.eu `__ - Issuer: Let's Encrypt `Verification `__ +* `seeks.hsbp.org `__ - Issuer: Let's Encrypt `Verification `__ - `PGP signed fingerprints of cert `__ +* `skyn3t.in/srx `__ - Issuer: Let's Encrypt | onion `hidden service `__ +* `spot.ecloud.global `__ - Issuer: Let's Encrypt `Verification `__ +* `srx.sx `__ - Issuer: Let's Encrypt `Verification `__ +* `stemy.me/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `suche.dasnetzundich.de `__ - Issuer: Let's Encrypt `Verification `__ +* `suche.elaon.de `__ - Issuer: Let's Encrypt `Verification `__ +* `suche.xyzco456vwisukfg.onion `__ +* `suche.uferwerk.org `__ - Issuer: Let's Encrypt `Verification `__ +* `timdor.noip.me/searx `__ - Issuer: Let's Encrypt `Verification `__ +* `trovu.komun.org `__ - Issuer: Let's Encrypt `Verification `__ +* `unmonito.red `__ - Issuer: Let's Encrypt `Verification `__ +* `www.finden.tk `__ - Issuer: Let's Encrypt `Verification `__ +* `zoek.anchel.nl `__ - Issuer: Let's Encrypt `Verification `__ + + Running in exclusive private walled-gardens =========================================== -These instances run in walled-gardens that exclude some segment of the general public (e.g. Tor users and users sharing IPs with many other users). Caution: privacy is also compromised on these sites due to exposure of cleartext traffic to a third party other than the website operator. -* [**intelme.com**](https://intelme.com) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=intelme.com) -* [**search404.io**](https://www.search404.io/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search404.io) -* [**searx.com.au**](https://searx.com.au/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.com.au) -* [**searx.lavatech.top**](https://searx.lavatech.top/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lavatech.top) -* [**searchx.mobi**](https://searchx.mobi/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searchx.mobi) -* [**searx.org**](https://searx.org/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.org) -* [**searx.run**](https://searx.run/) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.run) -* [**searx.world**](https://searx.world) - Issuer: Cloudflare [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.world) - Adds Amazon affiliate links +These instances run in walled-gardens that exclude some segment of the general +public (e.g. Tor users and users sharing IPs with many other users). Caution: +privacy is also compromised on these sites due to exposure of cleartext traffic +to a third party other than the website operator. + +* `intelme.com `__ - Issuer: Cloudflare `Verification `__ +* `search404.io `__ - Issuer: Cloudflare `Verification `__ +* `searx.com.au `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.lavatech.top `__ - Issuer: Cloudflare `Verification `__ +* `searchx.mobi `__ - Issuer: Cloudflare `Verification `__ +* `searx.org `__ - Issuer: Cloudflare `Verification `__ +* `searx.run `__ - Issuer: Cloudflare `Verification `__ +* `searx.world `__ - Issuer: Cloudflare `Verification `__ - Adds Amazon affiliate links + Running with an incorrect SSL certificate ========================================= -* [**listi.me**](https://listi.me/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=listi.me&latest) -* [**s.matejc.com**](https://s.matejc.com/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.matejc.com) -* [**search.jollausers.de**](https://search.jollausers.de) - Incorrectly configured [SSL certificate](https://www.ssllabs.com/ssltest/analyze.html?d=search.jollausers.de) -* [**search.paviro.de**](https://search.paviro.de) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.paviro.de) -* [**searx.abenthung.it**](https://searx.abenthung.it/) - Issuer: Comodo CA Limited [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.abenthung.it) -* [**searx.coding4schoki.org**](https://searx.coding4schoki.org/) - Incorrectly configured [SSL Certificate](https://www.ssllabs.com/ssltest/analyze.html?d=searx.coding4schoki.org) -* [**searx.haxors.club**](https://searx.haxors.club/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.haxors.club) -* [**searx.nulltime.net**](https://searx.nulltime.net/) (as [Hidden Service](http://searx7gwtu5rh6wr.onion)) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nulltime.net) -* [**searx.ch**](https://searx.ch/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ch) (cert clock problems) +* `listi.me `__ - Issuer: Let's Encrypt `Verification `__ +* `s.matejc.com `__ - Issuer: Let's Encrypt `Verification `__ +* `search.jollausers.de `__ - Incorrectly configured `SSL certificate `__ +* `search.paviro.de `__ - Issuer: LetsEncrypt `Verification `__ +* `searx.abenthung.it `__ - Issuer: Comodo CA Limited `Verification `__ +* `searx.coding4schoki.org `__ - Incorrectly configured `SSL Certificate `__ +* `searx.haxors.club `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.nulltime.net `__ (as `Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ +* `searx.ch `__ - Issuer: Let's Encrypt `Verification `__ (cert clock problems) + Offline ======= -* [**a.searx.space**](https://a.searx.space) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=a.searx.space) (unstable, under construction). -* [**anyonething.de**](https://anyonething.de) - (was found to have become a pastebin on or before 2019-03-01) Issuer: Comodo CA Limited (Warning: uses Cloudflare) [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=anyonething.de) -* [**h7jwxg5rakyfvikpi.onion**](http://7jwxg5rakyfvikpi.onion/) - available only as Tor Hidden Service (down on 2019-06-26) -* [**hacktivis.me/searx**](https://hacktivis.me/searx) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=hacktivis.me/searx) -* [**icebal.com**](https://icebal.com) - (down) Issuer: Let's Encrypt -* [**netrangler.host**](https://netrangler.host) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=netrangler.host) -* [**opengo.nl**](https://www.opengo.nl) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.opengo.nl) -* [**p9e.de**](https://p9e.de/) - (down - timeout) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=p9e.de) -* [**rubri.co**](https://rubri.co) - (down) Issuer: Let's Encrypt -* [**s.bacafe.xyz**](https://s.bacafe.xyz/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=s.bacafe.xyz&latest) -* [**search.alecpap.com**](https://search.alecpap.com/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.alecpap.com) -* [**search.blackit.de**](https://search.blackit.de/) - (down) Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.blackit.de) -* [**search.deblan.org**](https://search.deblan.org/) (down) - Issuer: COMODO via GANDI [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.deblan.org) -* [**search.homecomputing.fr**](https://search.homecomputing.fr/) - (down) Issuer: CAcert [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.homecomputing.fr) -* [**search.jpope.org**](https://search.jpope.org) - (down - timeout) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.jpope.org) -* [**search.kakise.xyz**](https://search.kakise.xyz/) - down -* [**search.kosebamse.com**](https://search.kosebamse.com) - Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.kosebamse.com) -* [**search.kujiu.org**](https://search.kujiu.org) - (down) Issuer: Let's Encrypt -* [**search.mailaender.coffee**](https://search.mailaender.coffee/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mailaender.coffee) -* [**search.matrix.ac**](https://search.matrix.ac) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=matrix.ac) -* [**search.mypsc.ca**](https://search.mypsc.ca/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.mypsc.ca) -* [**search.namedkitten.pw**](https://search.namedkitten.pw) - (SSL error) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.namedkitten.pw) -* [**search.opentunisia.org**](https://search.opentunisia.org) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.opentunisia.org) -* [**search.r3d007.com**](https://search.r3d007.com/) - (down) Issuer: Let's Encrypt -* [**search.static.lu**](https://search.static.lu/) - (down) Issuer: StartCom [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.static.lu) -* [**search.teej.xyz**](https://search.teej.xyz) - (down) Issuer: LetsEncrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.teej.xyz) -* [**search.wxzm.sx**](https://search.wxzm.sx) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=search.wxzm.sx) -* [**searx.4ray.co**](https://searx.4ray.co/) - (no longer an instance, redirects to main page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.4ray.co) -* [**searx.32bitflo.at**](https://searx.32bitflo.at/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.32bitflo.at) -* [**searx.ahh.si**](https://searx.ahh.si/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.ahh.si) -* [**searx.angristan.xyz**](https://searx.angristan.xyz/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.angristan.xyz) -* [**searx.antirep.net**](https://searx.antirep.net/) - (return a 502 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.antirep.net) -* [**searx.aquilenet.fr**](https://searx.aquilenet.fr/) - (down - 429 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.aquilenet.fr) -* [**searx.at**](https://searx.at/) - (return "request exception" at every search) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.at) -* [**searx.cc**](https://searx.cc/) - (down on 2019-06-26) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.cc) -* [**searx.dk**](https://searx.dk/) - (down - 429 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.dk) -* [**searx.ehrmanns.ch**](https://searx.ehrmanns.ch) - (down) Issuer: Let's Encrypt -* [**searx.glibre.net**](https://searx.glibre.net) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.glibre.net) -* [**searx.infini.fr**](https://searx.infini.fr) - (return a page stating that the website is not installed) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.infini.fr) -* [**searx.jeanphilippemorvan.info**](https://searx.jeanphilippemorvan.info/) - (down) Issuer: StartCom [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.jeanphilippemorvan.info) -* [**searx.lhorn.de**](https://searx.lhorn.de/) - (redirect the Searx's github repository page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lhorn.de&latest) (only reachable from european countries) -* [**searx.lvweb.host**](https://searx.lvweb.host) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.lvweb.host) -* [**searx.mrtino.eu**](https://searx.mrtino.eu) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.mrtino.eu) -* [**searx.netzspielplatz.de**](https://searx.netzspielplatz.de/) - (error page about GDPR even when browsing it from USA and Asia) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.netzspielplatz.de) -* [**searx.new-admin.net**](https://searx.new-admin.net) - (down) Issuer: Let's Encrypt -* [**searx.nogafa.org**](https://searx.nogafa.org/)- (broken CSS) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.nogafa.org) -* [**searx.potato.hu**](https://searx.potato.hu) - (not a searx instance) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.potato.hu) -* [**searx.rubbeldiekatz.info**](https://searx.rubbeldiekatz.info/) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.rubbeldiekatz.info/) -* [**searx.s42.space**](https://searx.s42.space) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.s42.space) -* [**searx.salcay.hu**](https://searx.salcay.hu/) - (down - blank page) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.salcay.hu) -* [**searx.selea.se**](https://searx.selea.se) - (Leads to default Apache page) Issuer: RapidSSL (HSTS preloaded, DNSSEC) [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.selea.se) | [HSTS Preload](https://hstspreload.org/?domain=searx.selea.se) -* [**searx.steinscraft.net**](https://searx.steinscraft.net/) - (down) Issuer: Cloudflare -* [**searx.techregion.de**](https://searx.techregion.de/) - (domain expired) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.techregion.de) -* [**searx.tognella.com**](https://searx.tognella.com/) - (down) Issuer: Cloudflare -* [**searx.xi.ht**](https://searx.xi.ht/) - (return a 502 HTTP error) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searx.xi.ht) -* [**searxist.com**](https://searxist.com/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=searxist.com) -* [**so.sb**](https://so.sb/) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=so.sb) -* [**srx.stdout.net**](https://srx.stdout.net/) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=srx.stdout.net) -* [**w6f7cgdm54cyvohcuhraaafhajctyj3ihenrovuxogoagrr5g43qmoid.onion**](http://w6f7cgdm54cyvohcuhraaafhajctyj3ihenrovuxogoagrr5g43qmoid.onion/) - Hidden Service -* [**win8linux.nohost.me**](https://win8linux.nohost.me/searx/) - (down) Issuer: Let's Encrypt -* [**wiznet.tech**](https://wiznet.tech) - (down) - Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=wiznet.tech) -* [**www.mercurius.space**](https://www.mercurius.space/) - (down) Issuer: Let's Encrypt -* [**www.ready.pm**](https://www.ready.pm) - Issuer: WoSign [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=www.ready.pm) -* [**z.awsmppl.com**](https://z.awsmppl.com) - (down) Issuer: Let's Encrypt [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=z.awsmppl.com) -* [**zlsdzh.tk**](https://zlsdzh.tk) - (down - 404 HTTP error) Issuer: TrustAsia Technologies, Inc. [Verification](https://www.ssllabs.com/ssltest/analyze.html?d=zlsdzh.tk)* +* `a.searx.space `__ - Issuer: Let's Encrypt `Verification `__ (unstable, under construction). +* `anyonething.de `__ - (was found to have become a pastebin on or before 2019-03-01) Issuer: Comodo CA Limited (Warning: uses Cloudflare) `Verification `__ +* `h7jwxg5rakyfvikpi.onion `__ - available only as Tor Hidden Service (down on 2019-06-26) +* `hacktivis.me/searx `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `icebal.com `__ - (down) Issuer: Let's Encrypt +* `netrangler.host `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `opengo.nl `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `p9e.de `__ - (down - timeout) Issuer: Let's Encrypt `Verification `__ +* `rubri.co `__ - (down) Issuer: Let's Encrypt +* `s.bacafe.xyz `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `search.alecpap.com `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `search.blackit.de `__ - (down) Let's Encrypt `Verification `__ +* `search.deblan.org `__ (down) - Issuer: COMODO via GANDI `Verification `__ +* `search.homecomputing.fr `__ - (down) Issuer: CAcert `Verification `__ +* `search.jpope.org `__ - (down - timeout) Issuer: Let's Encrypt `Verification `__ +* `search.kakise.xyz `__ - down +* `search.kosebamse.com `__ - Issuer: LetsEncrypt `Verification `__ +* `search.kujiu.org `__ - (down) Issuer: Let's Encrypt +* `search.mailaender.coffee `__ - Issuer: Let's Encrypt `Verification `__ +* `search.matrix.ac `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `search.mypsc.ca `__ - Issuer: Let's Encrypt `Verification `__ +* `search.namedkitten.pw `__ - (SSL error) - Issuer: Let's Encrypt `Verification `__ +* `search.opentunisia.org `__ - Issuer: Let's Encrypt `Verification `__ +* `search.r3d007.com `__ - (down) Issuer: Let's Encrypt +* `search.static.lu `__ - (down) Issuer: StartCom `Verification `__ +* `search.teej.xyz `__ - (down) Issuer: LetsEncrypt `Verification `__ +* `search.wxzm.sx `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.4ray.co `__ - (no longer an instance, redirects to main page) Issuer: Let's Encrypt `Verification `__ +* `searx.32bitflo.at `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.ahh.si `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `searx.angristan.xyz `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.antirep.net `__ - (return a 502 HTTP error) Issuer: Let's Encrypt `Verification `__ +* `searx.aquilenet.fr `__ - (down - 429 HTTP error) Issuer: Let's Encrypt `Verification `__ +* `searx.at `__ - (return "request exception" at every search) Issuer: Let's Encrypt `Verification `__ +* `searx.cc `__ - (down on 2019-06-26) Issuer: Let's Encrypt `Verification `__ +* `searx.dk `__ - (down - 429 HTTP error) Issuer: Let's Encrypt `Verification `__ +* `searx.ehrmanns.ch `__ - (down) Issuer: Let's Encrypt +* `searx.glibre.net `__ - Issuer: Let's Encrypt `Verification `__ +* `searx.infini.fr `__ - (return a page stating that the website is not installed) Issuer: Let's Encrypt `Verification `__ +* `searx.jeanphilippemorvan.info `__ - (down) Issuer: StartCom `Verification `__ +* `searx.lhorn.de `__ - (redirect the Searx's github repository page) Issuer: Let's Encrypt `Verification `__ (only reachable from european countries) +* `searx.lvweb.host `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.mrtino.eu `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.netzspielplatz.de `__ - (error page about GDPR even when browsing it from USA and Asia) - Issuer: Let's Encrypt `Verification `__ +* `searx.new-admin.net `__ - (down) Issuer: Let's Encrypt +* `searx.nogafa.org `__ - (broken CSS) Issuer: Let's Encrypt `Verification `__ +* `searx.potato.hu `__ - (not a searx instance) - Issuer: Let's Encrypt `Verification `__ +* `searx.rubbeldiekatz.info `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.s42.space `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `searx.salcay.hu `__ - (down - blank page) Issuer: Let's Encrypt `Verification `__ +* `searx.selea.se `__ - (Leads to default Apache page) Issuer: RapidSSL (HSTS preloaded, DNSSEC) `Verification `__ | `HSTS Preload `__ +* `searx.steinscraft.net `__ - (down) Issuer: Cloudflare +* `searx.techregion.de `__ - (domain expired) - Issuer: Let's Encrypt `Verification `__ +* `searx.tognella.com `__ - (down) Issuer: Cloudflare +* `searx.xi.ht `__ - (return a 502 HTTP error) Issuer: Let's Encrypt `Verification `__ +* `searxist.com `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `so.sb `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `srx.stdout.net `__ - Issuer: Let's Encrypt `Verification `__ +* `w6f7cgdm54cyvohcuhraaafhajctyj3ihenrovuxogoagrr5g43qmoid.onion `__ - Hidden Service +* `win8linux.nohost.me `__ - (down) Issuer: Let's Encrypt +* `wiznet.tech `__ - (down) - Issuer: Let's Encrypt `Verification `__ +* `www.mercurius.space `__ - (down) Issuer: Let's Encrypt +* `www.ready.pm `__ - Issuer: WoSign `Verification `__ +* `z.awsmppl.com `__ - (down) Issuer: Let's Encrypt `Verification `__ +* `zlsdzh.tk `__ - (down - 404 HTTP error) Issuer: TrustAsia Technologies, Inc. `Verification `__ * + -- cgit v1.2.3 From 3bb97fcb84246f99cbbe3199f8a81fdabaaef997 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 5 Jan 2020 10:02:42 +0100 Subject: docs(user): public instances, fix Searxes@Danwin entry fixes: https://github.com/asciimoo/searx/issues/1770 This is not Searx at all. This is Meta-Searx with other engines. See https://github.com/asciimoo/searx/issues/1770#issuecomment-570776655 Signed-off-by: Markus Heiser --- docs/user/public_instances.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/public_instances.rst b/docs/user/public_instances.rst index a88acc479..b0cdd8d15 100644 --- a/docs/user/public_instances.rst +++ b/docs/user/public_instances.rst @@ -51,6 +51,16 @@ you can't decide which Searx instance to use: - Excludes servers with user tracking and analytics or are proxied through Cloudflare. + * - `Searxes `__ @Danwin + - onion v3 `hidden service + `__ + - Let's Encrypt (`Verification + `__) + - sources data from a randomly selected running server that satisfies + admin's quality standards which is used for post-processing + - filters out privacy-hostile websites (like CloudFlare) and either marks + them as such or folds them below the high ranking results. + Alive and running ================= @@ -169,7 +179,6 @@ Alive and running * `searx.xyz `__ - Issuer: Let's Encrypt `Verification `__ * `searx.zareldyn.net `__ - Issuer: Let's Encrypt `Verification `__ * `searx.zdechov.net `__ - Issuer: Let's Encrypt `Verification `__ -* `searxes.eu.org `__ (`As Hidden Service `__) - Issuer: Let's Encrypt `Verification `__ * `searxs.eu `__ - Issuer: Let's Encrypt `Verification `__ * `seeks.hsbp.org `__ - Issuer: Let's Encrypt `Verification `__ - `PGP signed fingerprints of cert `__ * `skyn3t.in/srx `__ - Issuer: Let's Encrypt | onion `hidden service `__ -- cgit v1.2.3 From 0f4f0e517e40632f99ecfb7fe9682226c3cfddf1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 6 Jan 2020 14:31:18 +0100 Subject: docs(user): move wiki/Searx-instances from wiki to docs fixed some reST markups Signed-off-by: Markus Heiser --- docs/user/public_instances.rst | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/user/public_instances.rst b/docs/user/public_instances.rst index b0cdd8d15..37138786b 100644 --- a/docs/user/public_instances.rst +++ b/docs/user/public_instances.rst @@ -11,15 +11,27 @@ Public Searx instances ====================== +.. _mailing list: mailto:searx-instances@autistici.org +.. _subscription page: https://www.autistici.org/mailman/listinfo/searx-instances + + Useful information ================== -* Up-to-date health report available on https://stats.searx.xyz(1), for onion (tor) services: https://stats.searx.xyz/tor.html -* Searx instances `mailing list `__ & `subscription page `__. -* Some of the Searx instances have a CAcert SSL certificate. You can install the missing root cert `from here `__. -* You can add your own Searx instance to this page by clicking `here `__ or by clicking on the "Edit" button in the top right corner (when logged in). A GitHub account is required to make changes. +* Up-to-date health report available on https://stats.searx.xyz [1]_, for onion + (tor) services: https://stats.searx.xyz/tor.html + +* Searx instances `mailing list`_ & `subscription page`_. + +* Some of the Searx instances have a CAcert SSL certificate. You can install the + missing root cert `from here `__. + +* To add your own Searx instance to this page send us your PR. A GitHub account + is required to send PR or add an issue. + +.. [1] Note that most of the instances with a A+ grade in CSP column in this + site are not fully functional - for example auto-completion may not work. -(1) Note that most of the instances with a A+ grade in CSP column in this site are not fully functional - for example auto-completion may not work. List of public Searx instances ============================== @@ -44,7 +56,7 @@ you can't decide which Searx instance to use: * - `Neocities `__ - n/a - - Comodo (`verification `__) + - Comodo (`Verification `__) - Redirects users directly to a random selection of any known running server after entering query. Requires Javascript. `Changelog `__. @@ -65,10 +77,16 @@ you can't decide which Searx instance to use: Alive and running ================= -**NOTE:** Public instances listed here may yield less accurate results as they have much higher traffic and consequently have a higher chance of being blocked by search providers such as Google, Qwant, Bing, Startpage, etc. Hosting your own instance or using an instance that isn't listed here may give you a more consistent search experience. - **BEFORE EDITING**: Please add your Searx instance by respecting the alphabetic order. +.. note:: + + Public instances listed here may yield less accurate results as they have + much higher traffic and consequently have a higher chance of being blocked by + search providers such as Google, Qwant, Bing, Startpage, etc. Hosting your + own instance or using an instance that isn't listed here may give you a more + consistent search experience. + * `ai.deafpray.wtf/searx `__ - Issuer: Let's Encrypt `Verification `__ * `bamboozle.it `__ - Issuer: Let's Encrypt `Verification `__ * `bee.jaekr.dev `__ - Issuer: Let's Encrypt `Verification `__ -- cgit v1.2.3 From 86b51636410cdf699727c9d64ffb6520ef5a0dad Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 6 Jan 2020 15:06:36 +0100 Subject: docs: move wiki/Searx-instances from wiki to docs fix project link in conf.py Signed-off-by: Markus Heiser --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index be0c9d6ee..af255e230 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -94,7 +94,7 @@ html_context = { "project_links": [ ProjectLink("Source", GIT_URL), ProjectLink("Wiki", "https://github.com/asciimoo/searx/wiki"), - ProjectLink("Public instances", "https://github.com/asciimoo/searx/wiki/Searx-instances"), + ProjectLink("Public instances", "https://asciimoo.github.io/searx/user/public_instances.html"), ProjectLink("Twitter", "https://twitter.com/Searx_engine"), ] } -- cgit v1.2.3 From e84067816b7d9cd83569a5b90385ba40cbc4e2fe Mon Sep 17 00:00:00 2001 From: Emilien Devos Date: Sun, 12 Jan 2020 10:48:29 +0000 Subject: searx.be stopped using Fathom analytics --- docs/user/public_instances.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/public_instances.rst b/docs/user/public_instances.rst index 37138786b..9665c58b7 100644 --- a/docs/user/public_instances.rst +++ b/docs/user/public_instances.rst @@ -142,7 +142,7 @@ Alive and running * `search.tolstoevsky.ml `__ - Issuer: Let's Encrypt `Verification `__ * `searchsin.com/searx `__ - Issuer: Let's Encrypt `Verification `__ * `searx.anongoth.pl `__ - Issuer: Let's Encrypt `Verification `__ -* `searx.be `__ - Issuer: Let's Encrypt `Verification `__ - Uses Fathom Analytics for user tracking and analytics +* `searx.be `__ - Issuer: Let's Encrypt `Verification `__ * `searx.ca `__ - Issuer: Let's Encrypt `Verification `__ * `searx.canox.net `__ - Issuer: Let's Encrypt `Verification `__ * `searx.cybt.de `__ - Issuer: Let's Encrypt `Verification `__ -- cgit v1.2.3