diff --git a/Makefile b/Makefile
index b69202ba2..f35b86c41 100644
--- a/Makefile
+++ b/Makefile
@@ -8,6 +8,9 @@ PYOBJECTS = searx
DOC = docs
PY_SETUP_EXTRAS ?= \[test\]
+PYDIST=./dist/py
+PYBUILD=./build/py
+
include utils/makefile.include
include utils/makefile.python
include utils/makefile.sphinx
@@ -23,6 +26,7 @@ help:
@echo ' install - developer install (./local)'
@echo ' uninstall - uninstall (./local)'
@echo ' gh-pages - build docs & deploy on gh-pages branch'
+ @echo ' clean - drop builds and environments'
@echo ''
@$(MAKE) -s -f utils/makefile.include make-help
@echo ''
diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css
index 10f5b4eda..d6a664f0f 100644
--- a/docs/_themes/searx/static/searx.css
+++ b/docs/_themes/searx/static/searx.css
@@ -24,7 +24,107 @@ p.sidebar-title, .sidebar p {
margin: 6pt;
}
-.sidebar li {
+.sidebar li,
+.hlist li {
list-style-type: disclosure-closed;
}
+
+/* admonitions
+*/
+
+div.admonition, div.topic {
+ background-color: #fafafa;
+ margin: 8px 0px;
+ padding: 1em;
+ 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
+ * ....
+*/
+
+div.rst-example {
+ background-color: inherit;
+ margin: 0;
+ border-top: none;
+ border-right: 1px solid #ccc;
+ border-bottom: none;
+ border-left: none;
+ border-radius: none;
+ padding: 0;
+}
+
+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
+ */
+
+div.highlight pre {
+ text-align: left;
+}
+
+/* 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;
+}
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/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/engines.rst b/docs/admin/engines.rst
new file mode 100644
index 000000000..4b78c8c2b
--- /dev/null
+++ b/docs/admin/engines.rst
@@ -0,0 +1,71 @@
+.. _engines generic:
+
+=======
+Engines
+=======
+
+.. sidebar:: Further reading ..
+
+ - :ref:`settings engine`
+ - :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**
+------------- ----------- -------------------- ------------
+Safe search **SS**
+------------- ----------- ---------------------------------
+Weigth **W**
+------------- ----------- ---------------------------------
+Disabled **D**
+============= =========== =================================
+
+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
+ - W
+ - D
+
+ {% 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.weight or 1 }}
+ - {{(mod.disabled and "y") or ""}}
+
+ {% endfor %}
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
index f3a995769..b3c7f5119 100644
--- a/docs/admin/index.rst
+++ b/docs/admin/index.rst
@@ -6,6 +6,11 @@ Administrator documentation
:maxdepth: 1
installation
+ settings
api
+ architecture
filtron
morty
+ engines
+ plugins
+ buildhosts
diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst
index 239ce0704..15800fc01 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/
@@ -151,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;
@@ -180,14 +186,13 @@ Add this configuration in the server config file
.. code:: nginx
- location = /searx { rewrite ^ /searx/; }
- location /searx {
- try_files $uri @searx;
+ location /searx/static {
+ alias /usr/local/searx/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;
}
@@ -197,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;
@@ -338,4 +347,3 @@ References
* How to: `Setup searx in a couple of hours with a free SSL certificate
`__
-
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/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/conf.py b/docs/conf.py
index c0bd246ac..af255e230 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,11 +14,18 @@ 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 --------------------------------------------------------------
master_doc = "index"
source_suffix = '.rst'
+numfig = True
+
+from searx import webapp
+jinja_contexts = {
+ 'webapp': dict(**webapp.__dict__)
+}
# usage:: lorem :patch:`f373169` ipsum
extlinks = {}
@@ -32,21 +39,40 @@ 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: ')
+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'] = (
+ '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.imgmath',
'sphinx.ext.extlinks',
'sphinx.ext.viewcode',
"sphinx.ext.autodoc",
"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.kfigure', # Sphinx extension which implements scalable image handling.
+ "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs
]
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),
+ "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
+ "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
}
issues_github_path = "asciimoo/searx"
@@ -54,16 +80,21 @@ 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": [
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"),
]
}
diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst
index 064f28e63..459dfb448 100644
--- a/docs/dev/contribution_guide.rst
+++ b/docs/dev/contribution_guide.rst
@@ -1,3 +1,5 @@
+.. _how to contribute:
+
=================
How to contribute
=================
@@ -48,7 +50,20 @@ 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
+.. _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:
@@ -57,6 +72,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.
@@ -64,6 +82,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`.
@@ -79,6 +107,8 @@ Translation currently takes place on :ref:`transifex `.
Please, do not update translation files in the repo.
+.. _contrib docs:
+
Documentation
=============
@@ -91,7 +121,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 +131,7 @@ Here is an example which makes a complete rebuild:
...
The HTML pages are in dist/docs.
+.. _make docs-live:
live build
----------
@@ -110,9 +141,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 +155,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/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/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/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/index.rst b/docs/dev/index.rst
index 8e18066ca..cb913a82b 100644
--- a/docs/dev/index.rst
+++ b/docs/dev/index.rst
@@ -11,3 +11,5 @@ Developer documentation
search_api
plugins
translation
+ makefile
+ reST
diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst
new file mode 100644
index 000000000..f5957001c
--- /dev/null
+++ b/docs/dev/makefile.rst
@@ -0,0 +1,221 @@
+.. _makefile:
+
+================
+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. 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::
+
+ $ 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, use 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 a ``./searx/webapp.py``
+instance, disables *debug* option again and opens the URL in your favorite WEB
+browser (:man:`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/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
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
diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst
new file mode 100644
index 000000000..4dc1279f0
--- /dev/null
+++ b/docs/dev/reST.rst
@@ -0,0 +1,1428 @@
+.. _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 <.>`. For build prerequisites read
+:ref:`docs build`.
+
+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
+
+ - Sphinx-Primer_
+ - `Sphinx markup constructs`_
+ - reST_, docutils_, `docutils FAQ`_
+ - Sphinx_, `sphinx-doc FAQ`_
+ - `sphinx config`_, doctree_
+ - `sphinx cross references`_
+ - linuxdoc_
+ - intersphinx_
+ - sphinx-jinja_
+ - `Sphinx's autodoc`_
+ - `Sphinx's Python domain`_, `Sphinx's C domain`_
+ - SVG_, ImageMagick_
+ - DOT_, `Graphviz's dot`_, Graphviz_
+
+
+.. 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.
+
+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).
+ 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:
+
+Basic inline markup
+===================
+
+.. sidebar:: Inline markup
+
+ - :ref:`reST roles`
+ - :ref:`reST smart ref`
+
+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``).
+
+.. 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:
+
+Basic article structure
+=======================
+
+The basic structure of an article makes use of heading adornments to markup
+chapter, sections and subsections.
+
+.. _reST template:
+
+reST template
+-------------
+
+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
+ -------
+
+ lorem ..
+
+ .. _subsection refname:
+
+ Subsection
+ ~~~~~~~~~~
+
+ lorem ..
+
+
+Headings
+--------
+
+#. title - with overline for document title:
+
+ .. code:: reST
+
+ ==============
+ Document title
+ ==============
+
+
+#. chapter - with anchor named ``anchor name``:
+
+ .. code:: reST
+
+ .. _anchor name:
+
+ Chapter
+ =======
+
+#. section
+
+ .. code:: reST
+
+ Section
+ -------
+
+#. subsection
+
+ .. code:: reST
+
+ Subsection
+ ~~~~~~~~~~
+
+
+
+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 refs
+----------
+
+With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
+content becomes smart.
+
+.. 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`:
+
+.. code:: python
+
+ intersphinx_mapping = {
+ "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),
+ }
+
+
+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
+
+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:
+
+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 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 ```
+ 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
+================
+
+.. 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`. 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`` (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
+
+ .. _svg image example:
+
+ .. kernel-figure:: svg_image.svg
+ :alt: 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: SVG image example
+
+ Simple SVG image.
+
+To refer the figure, a caption block is needed: :ref:`svg image example`.
+
+DOT files (aka Graphviz)
+------------------------
+
+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
+given.
+
+- `Graphviz's dot`_
+- DOT_
+- Graphviz_
+
+A simple example is shown in :ref:`dot file example`:
+
+.. code:: reST
+
+ .. _dot file example:
+
+ .. kernel-figure:: hello.dot
+ :alt: hello world
+
+ DOT's hello world example
+
+.. admonition:: hello.dot
+ :class: rst-example
+
+ .. _dot file example:
+
+ .. kernel-figure:: hello.dot
+ :alt: hello world
+
+ DOT's hello world example
+
+``kernel-render`` DOT
+---------------------
+
+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:: reST
+
+ .. _dot render example:
+
+ .. kernel-render:: DOT
+ :alt: digraph
+ :caption: Embedded DOT (Graphviz) code
+
+ digraph foo {
+ "bar" -> "baz";
+ }
+
+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
+ render example`.
+
+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
+
+ .. _dot render example:
+
+ .. kernel-render:: DOT
+ :alt: digraph
+ :caption: Embedded DOT (Graphviz) code
+
+ digraph foo {
+ "bar" -> "baz";
+ }
+
+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
+ render example`.
+
+``kernel-render`` SVG
+---------------------
+
+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
+
+.. code:: reST
+
+ .. _svg render example:
+
+ .. kernel-render:: SVG
+ :caption: Embedded **SVG** markup
+ :alt: so-nw-arrow
+..
+
+ .. code:: xml
+
+
+
+
+.. admonition:: kernel-render SVG
+ :class: rst-example
+
+ .. _svg render example:
+
+ .. kernel-render:: SVG
+ :caption: Embedded **SVG** markup
+ :alt: so-nw-arrow
+
+
+
+
+
+
+
+.. _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.
+
+
+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
+---------------
+
+.. sidebar:: Note ..
+
+ - the term cannot have more than one line of text
+
+ - 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 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.
+
+ term 3 : classifier
+ Definition 3.
+
+ term 4 : classifier one : classifier two
+ Definition 4.
+
+.. admonition:: definition list
+ :class: rst-example
+
+ 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.
+
+ term 3 : classifier
+ Definition 3.
+
+ term 4 : classifier one : classifier two
+
+
+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 `)
+
+
+Admonitions
+===========
+
+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
+
+ .. admonition:: generic admonition title
+
+ 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 ..
+
+ .. note::
+
+ lorem ipsum ..
+
+ .. warning::
+
+ 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 ..
+
+
+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
+
+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 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
+ :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__)
+ }
+
+
+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_. Below a *group-tab* example from
+:ref:`docs build` is shown:
+
+.. literalinclude:: ../admin/buildhosts.rst
+ :language: reST
+ :start-after: .. _system requirements:
+ :end-before: .. _system requirements END:
+
+
+.. _math:
+
+Math equations
+==============
+
+.. _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
+
+.. sidebar:: About LaTeX
+
+ - `amsmath user guide`_
+ - Mathematics_
+ - :ref:`docs build`
+
+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
+package.
+
+To embed LaTeX markup in reST documents, use role :rst:role:`:math: