OwlBurst/Ponysearch
1
0
Fork 0
forked from Ponysearch/Ponysearch
Code Pull requests Activity

Merge pull request #752 from kvch/gh-pages

Browse source 
documentation update && new page
This commit is contained in:
Adam Tauber 2016-11-05 17:19:58 +01:00 committed by GitHub
commit 43d598d0bd
5 changed files with 162 additions and 116 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/conf.py
View file

@ -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.

170
docs/dev/engine_overview.rst
View file

@ -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 |
+---------------------+-----------+-----------------------------------------+
+----------------------+-----------+-----------------------------------------+
| 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 <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------+
+====================+===============================================================================================================+
| url | string, url of the result |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| content | string, general result-text |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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)* |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| url | string, url to the result site |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| title | string, title of the result *(partly implemented)* |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| content | *(partly implemented)* |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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 |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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 |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------+
+--------------------+--------------------------------------------------------------------------------------------------------------+
| url | string, url of the result |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| content | *(not implemented yet)* |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------+
| thumbnail | string, which is representing the url to a small-preview image |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------+
+--------------------+--------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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 <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published *(not implemented yet)* |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
+==================+=======================================================================================================================================+
| 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 <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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, which is the `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ of the result |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
| torrentfile | string, which is the torrentfile of the result |
+------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| magnetlink | string, `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ 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 <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published |
+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
+=========================+==============================================================================================================+
| url | string, url of the result |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| content | string, general result-text |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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 adress 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 |
+-------------------------+------------------------------------------------------------------------------------------------------------------------------------+
+-------------------------+--------------------------------------------------------------------------------------------------------------+

2
docs/dev/plugins.rst
View file

@ -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

3
docs/index.rst
View file

@ -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
@ -29,6 +29,7 @@ User documentation
:maxdepth: 1
user/search_syntax
user/own-instance
Administrator documentation
---------------------------

43
docs/user/own-instance.rst Normal file
View file

@ -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 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 <https://github.com/asciimoo/morty>`__ 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.
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.