free
/
searx
Watch 1
Star 0
Fork 0
Code Issues 0 Pull Requests 0 Releases 11 Wiki Activity
Browse Source

[doc] grammar & format fixes in engine overview

Noemi Vanyi 10 years ago
parent
4af0e52e94
commit
bcd6825fdc
3 changed files with 232 additions and 242 deletions
Split View Show Diff Stats
  1. 91
    94
      _sources/dev/engine_overview.txt
  2. 50
    54
      dev/engine_overview.html
  3. 91
    94
      docs/dev/engine_overview.rst

+ 91
- 94
_sources/dev/engine_overview.txt View File 

@@ -3,14 +3,13 @@ Engine overview
3 3
4 4
5 5 
 searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
6 
-so it is using different search engines to provide better results.
6 
+so it uses different search engines to provide better results.
7 7
8 
-Because there is no general search-api which can be used for every
9 
-search-engine, there must be build an adapter between searx and the
10 
-external search-engine. This adapters are stored in the folder
11 
-`*searx/engines* <https://github.com/asciimoo/searx/tree/master/searx/engines>`__,
12 
-and this site is build to make an general documentation about this
13 
-engines
8 
+Because there is no general search API which could be used for every
9 
+search engine, an adapter has to be built between searx and the
10 
+external search engines. Adapters are stored under the folder
11 
+`searx/engines
12 
+<https://github.com/asciimoo/searx/tree/master/searx/engines>`__.
14 13
15 14
16 15 
 .. contents::
 
@@ -19,17 +18,16 @@ engines
19 18 
 general engine configuration
20 19 
 ----------------------------
21 20
22 
-It is required to tell searx what results can the engine provide. The
23 
-arguments can be inserted in the engine file, or in the settings file
21 
+It is required to tell searx the type of results the engine provides. The
22 
+arguments can be set in the engine file or in the settings file
24 23 
 (normally ``settings.yml``). The arguments in the settings file override
25 
-the one in the engine file.
24 
+the ones in the engine file.
26 25
27 
-Really, it is for most options no difference if there are contained in
28 
-the engine-file or in the settings. But there is a standard where to
29 
-place specific arguments by default.
26 
+It does not matter if an options is stored in the engine file or in the
27 
+settings. However, the standard way is the following:
30 28
31 29
32 
-engine-file
30 
+engine file
33 31 
 ~~~~~~~~~~~
34 32
35 33 
 +---------------------+-----------+-----------------------------------------+
 
@@ -60,27 +58,27 @@ settings.yml
60 58 
 overrides
61 59 
 ~~~~~~~~~
62 60
63 
-There are some options, with have default values in the engine, but are
64 
-often overwritten by the settings. If the option is assigned in the
65 
-engine-file with ``None`` it has to be redefined in the settings,
66 
-otherwise searx is not starting with that engine.
67 
-
68 
-The naming of that overrides can be wathever you want. But we recommend
69 
-the using of already used overrides if possible:
70 
-
71 
-+-----------------------+----------+--------------------------------------------------------------+
72 
-| argument              | type     | information                                                  |
73 
-+=======================+==========+==============================================================+
74 
-| base\_url             | string   | base-url, can be overwrite to use same engine on other url   |
75 
-+-----------------------+----------+--------------------------------------------------------------+
76 
-| number\_of\_results   | int      | maximum number of results per request                        |
77 
-+-----------------------+----------+--------------------------------------------------------------+
78 
-| language              | string   | ISO code of language and country like en\_US                 |
79 
-+-----------------------+----------+--------------------------------------------------------------+
80 
-| api\_key              | string   | api-key if required by engine                                |
81 
-+-----------------------+----------+--------------------------------------------------------------+
82 
-
83 
-example-code
61 
+A few of the options have default values in the engine, but are
62 
+often overwritten by the settings. If ``None`` is assigned to an option
63 
+in the engine file, it has to be redefined in the settings,
64 
+otherwise searx will not start with that engine.
65 
+
66 
+The naming of that overrides is arbitrary. But the recommended
67 
+overrides are the following:
68 
+
69 
++-----------------------+----------+----------------------------------------------------------------+
70 
+| argument              | type     | information                                                    |
71 
++=======================+==========+================================================================+
72 
+| base\_url             | string   | base-url, can be overwritten to use same engine on other URL   |
73 
++-----------------------+----------+----------------------------------------------------------------+
74 
+| number\_of\_results   | int      | maximum number of results per request                          |
75 
++-----------------------+----------+----------------------------------------------------------------+
76 
+| language              | string   | ISO code of language and country like en\_US                   |
77 
++-----------------------+----------+----------------------------------------------------------------+
78 
+| api\_key              | string   | api-key if required by engine                                  |
79 
++-----------------------+----------+----------------------------------------------------------------+
80 
+
81 
+example code
84 82 
 ~~~~~~~~~~~~
85 83
86 84 
 .. code:: python
 
@@ -90,21 +88,20 @@ example-code
90 88 
     paging = True
91 89 
     language_support = True
92 90
93 
-doing request
94 
--------------
91 
+making a request
92 
+----------------
95 93
96 
-To perform a search you have to specific at least a url on which the
97 
-request is performing
94 
+To perform a search an URL have to be specified. In addition to
95 
+specifying an URL, arguments can be passed to the query.
98 96
99 97 
 passed arguments
100 98 
 ~~~~~~~~~~~~~~~~
101 99
102 
-This arguments can be used to calculate the search-query. Furthermore,
103 
-some of that parameters are filled with default values which can be
104 
-changed for special purpose.
100 
+These arguments can be used to construct the search query. Furthermore,
101 
+parameters with default value can be redefined for special purposes.
105 102
106 103 
 +----------------------+------------+------------------------------------------------------------------------+
107 
-| argument             | type       | default-value, informations                                            |
104 
+| argument             | type       | default-value, information                                             |
108 105 
 +======================+============+========================================================================+
109 106 
 | url                  | string     | ``''``                                                                 |
110 107 
 +----------------------+------------+------------------------------------------------------------------------+
 
@@ -132,27 +129,27 @@ changed for special purpose.
132 129 
 parsed arguments
133 130 
 ~~~~~~~~~~~~~~~~
134 131
135 
-The function ``def request(query, params):`` is always returning the
136 
-``params`` variable back. Inside searx, the following paramters can be
137 
-used to specific a search-request:
138 
-
139 
-+------------+-----------+----------------------------------------------------------+
140 
-| argument   | type      | information                                              |
141 
-+============+===========+==========================================================+
142 
-| url        | string    | requested url                                            |
143 
-+------------+-----------+----------------------------------------------------------+
144 
-| method     | string    | HTTP request methode                                     |
145 
-+------------+-----------+----------------------------------------------------------+
146 
-| headers    | set       | HTTP header informations                                 |
147 
-+------------+-----------+----------------------------------------------------------+
148 
-| data       | set       | HTTP data informations (parsed if ``method != 'GET'``)   |
149 
-+------------+-----------+----------------------------------------------------------+
150 
-| cookies    | set       | HTTP cookies                                             |
151 
-+------------+-----------+----------------------------------------------------------+
152 
-| verify     | boolean   | Performing SSL-Validity check                            |
153 
-+------------+-----------+----------------------------------------------------------+
154 
-
155 
-example-code
132 
+The function ``def request(query, params):`` always returns the
133 
+``params`` variable. Inside searx, the following paramters can be
134 
+used to specify a search request:
135 
+
136 
++------------+-----------+---------------------------------------------------------+
137 
+| argument   | type      | information                                             |
138 
++============+===========+=========================================================+
139 
+| url        | string    | requested url                                           |
140 
++------------+-----------+---------------------------------------------------------+
141 
+| method     | string    | HTTP request method                                     |
142 
++------------+-----------+---------------------------------------------------------+
143 
+| headers    | set       | HTTP header information                                 |
144 
++------------+-----------+---------------------------------------------------------+
145 
+| data       | set       | HTTP data information (parsed if ``method != 'GET'``)   |
146 
++------------+-----------+---------------------------------------------------------+
147 
+| cookies    | set       | HTTP cookies                                            |
148 
++------------+-----------+---------------------------------------------------------+
149 
+| verify     | boolean   | Performing SSL-Validity check                           |
150 
++------------+-----------+---------------------------------------------------------+
151 
+
152 
+example code
156 153 
 ~~~~~~~~~~~~
157 154
158 155 
 .. code:: python
 
@@ -171,10 +168,10 @@ example-code
171 168
172 169 
         return params
173 170
174 
-returning results
175 
------------------
171 
+returned results
172 
+----------------
176 173
177 
-Searx has the possiblity to return results in different media-types.
174 
+Searx is able to return results of different media-types.
178 175 
 Currently the following media-types are supported:
179 176
180 177 
 -  default
 
@@ -183,8 +180,8 @@ Currently the following media-types are supported:
183 180 
 -  torrent
184 181 
 -  map
185 182
186 
-to set another media-type as default, you must set the parameter
187 
-``template`` to the required type.
183 
+To set another media-type as default, the parameter
184 
+``template`` must be set to the desired type.
188 185
189 186 
 default
190 187 
 ~~~~~~~
 
@@ -246,31 +243,31 @@ videos
246 243 
 torrent
247 244 
 ~~~~~~~
248 245
249 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
250 
-| result-parameter | information                                                                                                                                           |
251 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
252 
-| template         | is set to ```torrent.html```                                                                                                                          |
253 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
254 
-| url              | string, which is representing the url of the result                                                                                                   |
255 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
256 
-| title            | string, which is representing the title of the result                                                                                                 |
257 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
258 
-| content          | string, which is giving a general result-text                                                                                                         |
259 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
260 
-| publishedDate    | [datetime.datetime](https://docs.python.org/2/library/datetime.html#datetime-objects), represent when the result is published _(not implemented yet)_ |
261 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
262 
-| seed             | int, number of seeder                                                                                                                                 |
263 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
264 
-| leech            | int, number of leecher                                                                                                                                |
265 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
266 
-| filesize         | int, size of file in bytes                                                                                                                            |
267 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
268 
-| files            | int, number of files                                                                                                                                  |
269 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
270 
-| magnetlink       | string, which is the [magnetlink](https://en.wikipedia.org/wiki/Magnet_URI_scheme) of the result                                                      |
271 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
272 
-| torrentfile      | string, which is the torrentfile of the result                                                                                                        |
273 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
246 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
247 
+| result-parameter | information                                                                                                                                              |
248 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
249 
+| template         | is set to ```torrent.html```                                                                                                                             |
250 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
251 
+| url              | string, which is representing the url of the result                                                                                                      |
252 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
253 
+| title            | string, which is representing the title of the result                                                                                                    |
254 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
255 
+| content          | string, which is giving a general result-text                                                                                                            |
256 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
257 
+| publishedDate    | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published *(not implemented yet)* |
258 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
259 
+| seed             | int, number of seeder                                                                                                                                    |
260 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
261 
+| leech            | int, number of leecher                                                                                                                                   |
262 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
263 
+| filesize         | int, size of file in bytes                                                                                                                               |
264 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
265 
+| files            | int, number of files                                                                                                                                     |
266 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
267 
+| magnetlink       | string, which is the `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ of the result                                                      |
268 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
269 
+| torrentfile      | string, which is the torrentfile of the result                                                                                                           |
270 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
274 271
275 272
276 273 
 map

+ 50
- 54
dev/engine_overview.html View File 

@@ -42,31 +42,29 @@
42 42 
   <div class="section" id="engine-overview">
43 43 
 <h1><a class="toc-backref" href="#id2">Engine overview</a><a class="headerlink" href="#engine-overview" title="Permalink to this headline">¶</a></h1>
44 44 
 <p>searx is a <a class="reference external" href="https://en.wikipedia.org/wiki/Metasearch_engine">metasearch-engine</a>,
45 
-so it is using different search engines to provide better results.</p>
46 
-<p>Because there is no general search-api which can be used for every
47 
-search-engine, there must be build an adapter between searx and the
48 
-external search-engine. This adapters are stored in the folder
49 
-<a class="reference external" href="https://github.com/asciimoo/searx/tree/master/searx/engines">*searx/engines*</a>,
50 
-and this site is build to make an general documentation about this
51 
-engines</p>
45 
+so it uses different search engines to provide better results.</p>
46 
+<p>Because there is no general search API which could be used for every
47 
+search engine, an adapter has to be built between searx and the
48 
+external search engines. Adapters are stored under the folder
49 
+<a class="reference external" href="https://github.com/asciimoo/searx/tree/master/searx/engines">searx/engines</a>.</p>
52 50 
 <div class="contents topic" id="contents">
53 51 
 <p class="topic-title first">Contents</p>
54 52 
 <ul class="simple">
55 53 
 <li><a class="reference internal" href="#engine-overview" id="id2">Engine overview</a><ul>
56 54 
 <li><a class="reference internal" href="#general-engine-configuration" id="id3">general engine configuration</a><ul>
57 
-<li><a class="reference internal" href="#engine-file" id="id4">engine-file</a></li>
55 
+<li><a class="reference internal" href="#engine-file" id="id4">engine file</a></li>
58 56 
 <li><a class="reference internal" href="#settings-yml" id="id5">settings.yml</a></li>
59 57 
 <li><a class="reference internal" href="#overrides" id="id6">overrides</a></li>
60 
-<li><a class="reference internal" href="#example-code" id="id7">example-code</a></li>
58 
+<li><a class="reference internal" href="#example-code" id="id7">example code</a></li>
61 59 
 </ul>
62 60 
 </li>
63 
-<li><a class="reference internal" href="#doing-request" id="id8">doing request</a><ul>
61 
+<li><a class="reference internal" href="#making-a-request" id="id8">making a request</a><ul>
64 62 
 <li><a class="reference internal" href="#passed-arguments" id="id9">passed arguments</a></li>
65 63 
 <li><a class="reference internal" href="#parsed-arguments" id="id10">parsed arguments</a></li>
66 
-<li><a class="reference internal" href="#id1" id="id11">example-code</a></li>
64 
+<li><a class="reference internal" href="#id1" id="id11">example code</a></li>
67 65 
 </ul>
68 66 
 </li>
69 
-<li><a class="reference internal" href="#returning-results" id="id12">returning results</a><ul>
67 
+<li><a class="reference internal" href="#returned-results" id="id12">returned results</a><ul>
70 68 
 <li><a class="reference internal" href="#default" id="id13">default</a></li>
71 69 
 <li><a class="reference internal" href="#images" id="id14">images</a></li>
72 70 
 <li><a class="reference internal" href="#videos" id="id15">videos</a></li>
 
@@ -80,15 +78,14 @@ engines</p>
80 78 
 </div>
81 79 
 <div class="section" id="general-engine-configuration">
82 80 
 <h2><a class="toc-backref" href="#id3">general engine configuration</a><a class="headerlink" href="#general-engine-configuration" title="Permalink to this headline">¶</a></h2>
83 
-<p>It is required to tell searx what results can the engine provide. The
84 
-arguments can be inserted in the engine file, or in the settings file
81 
+<p>It is required to tell searx the type of results the engine provides. The
82 
+arguments can be set in the engine file or in the settings file
85 83 
 (normally <code class="docutils literal"><span class="pre">settings.yml</span></code>). The arguments in the settings file override
86 
-the one in the engine file.</p>
87 
-<p>Really, it is for most options no difference if there are contained in
88 
-the engine-file or in the settings. But there is a standard where to
89 
-place specific arguments by default.</p>
84 
+the ones in the engine file.</p>
85 
+<p>It does not matter if an options is stored in the engine file or in the
86 
+settings. However, the standard way is the following:</p>
90 87 
 <div class="section" id="engine-file">
91 
-<h3><a class="toc-backref" href="#id4">engine-file</a><a class="headerlink" href="#engine-file" title="Permalink to this headline">¶</a></h3>
88 
+<h3><a class="toc-backref" href="#id4">engine file</a><a class="headerlink" href="#engine-file" title="Permalink to this headline">¶</a></h3>
92 89 
 <table border="1" class="docutils">
93 90 
 <colgroup>
94 91 
 <col width="29%" />
 
@@ -153,17 +150,17 @@ place specific arguments by default.</p>
153 150 
 </div>
154 151 
 <div class="section" id="overrides">
155 152 
 <h3><a class="toc-backref" href="#id6">overrides</a><a class="headerlink" href="#overrides" title="Permalink to this headline">¶</a></h3>
156 
-<p>There are some options, with have default values in the engine, but are
157 
-often overwritten by the settings. If the option is assigned in the
158 
-engine-file with <code class="docutils literal"><span class="pre">None</span></code> it has to be redefined in the settings,
159 
-otherwise searx is not starting with that engine.</p>
160 
-<p>The naming of that overrides can be wathever you want. But we recommend
161 
-the using of already used overrides if possible:</p>
153 
+<p>A few of the options have default values in the engine, but are
154 
+often overwritten by the settings. If <code class="docutils literal"><span class="pre">None</span></code> is assigned to an option
155 
+in the engine file, it has to be redefined in the settings,
156 
+otherwise searx will not start with that engine.</p>
157 
+<p>The naming of that overrides is arbitrary. But the recommended
158 
+overrides are the following:</p>
162 159 
 <table border="1" class="docutils">
163 160 
 <colgroup>
164 161 
 <col width="24%" />
165 
-<col width="11%" />
166 
-<col width="65%" />
162 
+<col width="10%" />
163 
+<col width="66%" />
167 164 
 </colgroup>
168 165 
 <thead valign="bottom">
169 166 
 <tr class="row-odd"><th class="head">argument</th>
 
@@ -174,7 +171,7 @@ the using of already used overrides if possible:</p>
174 171 
 <tbody valign="top">
175 172 
 <tr class="row-even"><td>base_url</td>
176 173 
 <td>string</td>
177 
-<td>base-url, can be overwrite to use same engine on other url</td>
174 
+<td>base-url, can be overwritten to use same engine on other URL</td>
178 175 
 </tr>
179 176 
 <tr class="row-odd"><td>number_of_results</td>
180 177 
 <td>int</td>
 
@@ -192,7 +189,7 @@ the using of already used overrides if possible:</p>
192 189 
 </table>
193 190 
 </div>
194 191 
 <div class="section" id="example-code">
195 
-<h3><a class="toc-backref" href="#id7">example-code</a><a class="headerlink" href="#example-code" title="Permalink to this headline">¶</a></h3>
192 
+<h3><a class="toc-backref" href="#id7">example code</a><a class="headerlink" href="#example-code" title="Permalink to this headline">¶</a></h3>
196 193 
 <div class="code python highlight-python"><div class="highlight"><pre><span class="c"># engine dependent config</span>
197 194 
 <span class="n">categories</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;general&#39;</span><span class="p">]</span>
198 195 
 <span class="n">paging</span> <span class="o">=</span> <span class="bp">True</span>
 
@@ -201,15 +198,14 @@ the using of already used overrides if possible:</p>
201 198 
 </div>
202 199 
 </div>
203 200 
 </div>
204 
-<div class="section" id="doing-request">
205 
-<h2><a class="toc-backref" href="#id8">doing request</a><a class="headerlink" href="#doing-request" title="Permalink to this headline">¶</a></h2>
206 
-<p>To perform a search you have to specific at least a url on which the
207 
-request is performing</p>
201 
+<div class="section" id="making-a-request">
202 
+<h2><a class="toc-backref" href="#id8">making a request</a><a class="headerlink" href="#making-a-request" title="Permalink to this headline">¶</a></h2>
203 
+<p>To perform a search an URL have to be specified. In addition to
204 
+specifying an URL, arguments can be passed to the query.</p>
208 205 
 <div class="section" id="passed-arguments">
209 206 
 <h3><a class="toc-backref" href="#id9">passed arguments</a><a class="headerlink" href="#passed-arguments" title="Permalink to this headline">¶</a></h3>
210 
-<p>This arguments can be used to calculate the search-query. Furthermore,
211 
-some of that parameters are filled with default values which can be
212 
-changed for special purpose.</p>
207 
+<p>These arguments can be used to construct the search query. Furthermore,
208 
+parameters with default value can be redefined for special purposes.</p>
213 209 
 <table border="1" class="docutils">
214 210 
 <colgroup>
215 211 
 <col width="21%" />
 
@@ -219,7 +215,7 @@ changed for special purpose.</p>
219 215 
 <thead valign="bottom">
220 216 
 <tr class="row-odd"><th class="head">argument</th>
221 217 
 <th class="head">type</th>
222 
-<th class="head">default-value, informations</th>
218 
+<th class="head">default-value, information</th>
223 219 
 </tr>
224 220 
 </thead>
225 221 
 <tbody valign="top">
 
@@ -272,14 +268,14 @@ changed for special purpose.</p>
272 268 
 </div>
273 269 
 <div class="section" id="parsed-arguments">
274 270 
 <h3><a class="toc-backref" href="#id10">parsed arguments</a><a class="headerlink" href="#parsed-arguments" title="Permalink to this headline">¶</a></h3>
275 
-<p>The function <code class="docutils literal"><span class="pre">def</span> <span class="pre">request(query,</span> <span class="pre">params):</span></code> is always returning the
276 
-<code class="docutils literal"><span class="pre">params</span></code> variable back. Inside searx, the following paramters can be
277 
-used to specific a search-request:</p>
271 
+<p>The function <code class="docutils literal"><span class="pre">def</span> <span class="pre">request(query,</span> <span class="pre">params):</span></code> always returns the
272 
+<code class="docutils literal"><span class="pre">params</span></code> variable. Inside searx, the following paramters can be
273 
+used to specify a search request:</p>
278 274 
 <table border="1" class="docutils">
279 275 
 <colgroup>
280 276 
 <col width="15%" />
281 277 
 <col width="14%" />
282 
-<col width="72%" />
278 
+<col width="71%" />
283 279 
 </colgroup>
284 280 
 <thead valign="bottom">
285 281 
 <tr class="row-odd"><th class="head">argument</th>
 
@@ -294,15 +290,15 @@ used to specific a search-request:</p>
294 290 
 </tr>
295 291 
 <tr class="row-odd"><td>method</td>
296 292 
 <td>string</td>
297 
-<td>HTTP request methode</td>
293 
+<td>HTTP request method</td>
298 294 
 </tr>
299 295 
 <tr class="row-even"><td>headers</td>
300 296 
 <td>set</td>
301 
-<td>HTTP header informations</td>
297 
+<td>HTTP header information</td>
302 298 
 </tr>
303 299 
 <tr class="row-odd"><td>data</td>
304 300 
 <td>set</td>
305 
-<td>HTTP data informations (parsed if <code class="docutils literal"><span class="pre">method</span> <span class="pre">!=</span> <span class="pre">'GET'</span></code>)</td>
301 
+<td>HTTP data information (parsed if <code class="docutils literal"><span class="pre">method</span> <span class="pre">!=</span> <span class="pre">'GET'</span></code>)</td>
306 302 
 </tr>
307 303 
 <tr class="row-even"><td>cookies</td>
308 304 
 <td>set</td>
 
@@ -316,7 +312,7 @@ used to specific a search-request:</p>
316 312 
 </table>
317 313 
 </div>
318 314 
 <div class="section" id="id1">
319 
-<h3><a class="toc-backref" href="#id11">example-code</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
315 
+<h3><a class="toc-backref" href="#id11">example code</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
320 316 
 <div class="code python highlight-python"><div class="highlight"><pre><span class="c"># search-url</span>
321 317 
 <span class="n">base_url</span> <span class="o">=</span> <span class="s">&#39;https://example.com/&#39;</span>
322 318 
 <span class="n">search_string</span> <span class="o">=</span> <span class="s">&#39;search?{query}&amp;page={page}&#39;</span>
 
@@ -334,9 +330,9 @@ used to specific a search-request:</p>
334 330 
 </div>
335 331 
 </div>
336 332 
 </div>
337 
-<div class="section" id="returning-results">
338 
-<h2><a class="toc-backref" href="#id12">returning results</a><a class="headerlink" href="#returning-results" title="Permalink to this headline">¶</a></h2>
339 
-<p>Searx has the possiblity to return results in different media-types.
333 
+<div class="section" id="returned-results">
334 
+<h2><a class="toc-backref" href="#id12">returned results</a><a class="headerlink" href="#returned-results" title="Permalink to this headline">¶</a></h2>
335 
+<p>Searx is able to return results of different media-types.
340 336 
 Currently the following media-types are supported:</p>
341 337 
 <ul class="simple">
342 338 
 <li>default</li>
 
@@ -345,8 +341,8 @@ Currently the following media-types are supported:</p>
345 341 
 <li>torrent</li>
346 342 
 <li>map</li>
347 343 
 </ul>
348 
-<p>to set another media-type as default, you must set the parameter
349 
-<code class="docutils literal"><span class="pre">template</span></code> to the required type.</p>
344 
+<p>To set another media-type as default, the parameter
345 
+<code class="docutils literal"><span class="pre">template</span></code> must be set to the desired type.</p>
350 346 
 <div class="section" id="default">
351 347 
 <h3><a class="toc-backref" href="#id13">default</a><a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h3>
352 348 
 <table border="1" class="docutils">
 
@@ -451,8 +447,8 @@ Currently the following media-types are supported:</p>
451 447 
 <h3><a class="toc-backref" href="#id16">torrent</a><a class="headerlink" href="#torrent" title="Permalink to this headline">¶</a></h3>
452 448 
 <table border="1" class="docutils">
453 449 
 <colgroup>
454 
-<col width="11%" />
455 
-<col width="89%" />
450 
+<col width="10%" />
451 
+<col width="90%" />
456 452 
 </colgroup>
457 453 
 <tbody valign="top">
458 454 
 <tr class="row-odd"><td>result-parameter</td>
 
@@ -471,7 +467,7 @@ Currently the following media-types are supported:</p>
471 467 
 <td>string, which is giving a general result-text</td>
472 468 
 </tr>
473 469 
 <tr class="row-even"><td>publishedDate</td>
474 
-<td>[datetime.datetime](<a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">https://docs.python.org/2/library/datetime.html#datetime-objects</a>), represent when the result is published _(not implemented yet)_</td>
470 
+<td><a class="reference external" href="https://docs.python.org/2/library/datetime.html#datetime-objects">datetime.datetime</a>, represent when the result is published <em>(not implemented yet)</em></td>
475 471 
 </tr>
476 472 
 <tr class="row-odd"><td>seed</td>
477 473 
 <td>int, number of seeder</td>
 
@@ -486,7 +482,7 @@ Currently the following media-types are supported:</p>
486 482 
 <td>int, number of files</td>
487 483 
 </tr>
488 484 
 <tr class="row-odd"><td>magnetlink</td>
489 
-<td>string, which is the [magnetlink](<a class="reference external" href="https://en.wikipedia.org/wiki/Magnet_URI_scheme">https://en.wikipedia.org/wiki/Magnet_URI_scheme</a>) of the result</td>
485 
+<td>string, which is the <a class="reference external" href="https://en.wikipedia.org/wiki/Magnet_URI_scheme">magnetlink</a> of the result</td>
490 486 
 </tr>
491 487 
 <tr class="row-even"><td>torrentfile</td>
492 488 
 <td>string, which is the torrentfile of the result</td>

+ 91
- 94
docs/dev/engine_overview.rst View File 

@@ -3,14 +3,13 @@ Engine overview
3 3
4 4
5 5 
 searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
6 
-so it is using different search engines to provide better results.
6 
+so it uses different search engines to provide better results.
7 7
8 
-Because there is no general search-api which can be used for every
9 
-search-engine, there must be build an adapter between searx and the
10 
-external search-engine. This adapters are stored in the folder
11 
-`*searx/engines* <https://github.com/asciimoo/searx/tree/master/searx/engines>`__,
12 
-and this site is build to make an general documentation about this
13 
-engines
8 
+Because there is no general search API which could be used for every
9 
+search engine, an adapter has to be built between searx and the
10 
+external search engines. Adapters are stored under the folder
11 
+`searx/engines
12 
+<https://github.com/asciimoo/searx/tree/master/searx/engines>`__.
14 13
15 14
16 15 
 .. contents::
 
@@ -19,17 +18,16 @@ engines
19 18 
 general engine configuration
20 19 
 ----------------------------
21 20
22 
-It is required to tell searx what results can the engine provide. The
23 
-arguments can be inserted in the engine file, or in the settings file
21 
+It is required to tell searx the type of results the engine provides. The
22 
+arguments can be set in the engine file or in the settings file
24 23 
 (normally ``settings.yml``). The arguments in the settings file override
25 
-the one in the engine file.
24 
+the ones in the engine file.
26 25
27 
-Really, it is for most options no difference if there are contained in
28 
-the engine-file or in the settings. But there is a standard where to
29 
-place specific arguments by default.
26 
+It does not matter if an options is stored in the engine file or in the
27 
+settings. However, the standard way is the following:
30 28
31 29
32 
-engine-file
30 
+engine file
33 31 
 ~~~~~~~~~~~
34 32
35 33 
 +---------------------+-----------+-----------------------------------------+
 
@@ -60,27 +58,27 @@ settings.yml
60 58 
 overrides
61 59 
 ~~~~~~~~~
62 60
63 
-There are some options, with have default values in the engine, but are
64 
-often overwritten by the settings. If the option is assigned in the
65 
-engine-file with ``None`` it has to be redefined in the settings,
66 
-otherwise searx is not starting with that engine.
67 
-
68 
-The naming of that overrides can be wathever you want. But we recommend
69 
-the using of already used overrides if possible:
70 
-
71 
-+-----------------------+----------+--------------------------------------------------------------+
72 
-| argument              | type     | information                                                  |
73 
-+=======================+==========+==============================================================+
74 
-| base\_url             | string   | base-url, can be overwrite to use same engine on other url   |
75 
-+-----------------------+----------+--------------------------------------------------------------+
76 
-| number\_of\_results   | int      | maximum number of results per request                        |
77 
-+-----------------------+----------+--------------------------------------------------------------+
78 
-| language              | string   | ISO code of language and country like en\_US                 |
79 
-+-----------------------+----------+--------------------------------------------------------------+
80 
-| api\_key              | string   | api-key if required by engine                                |
81 
-+-----------------------+----------+--------------------------------------------------------------+
82 
-
83 
-example-code
61 
+A few of the options have default values in the engine, but are
62 
+often overwritten by the settings. If ``None`` is assigned to an option
63 
+in the engine file, it has to be redefined in the settings,
64 
+otherwise searx will not start with that engine.
65 
+
66 
+The naming of that overrides is arbitrary. But the recommended
67 
+overrides are the following:
68 
+
69 
++-----------------------+----------+----------------------------------------------------------------+
70 
+| argument              | type     | information                                                    |
71 
++=======================+==========+================================================================+
72 
+| base\_url             | string   | base-url, can be overwritten to use same engine on other URL   |
73 
++-----------------------+----------+----------------------------------------------------------------+
74 
+| number\_of\_results   | int      | maximum number of results per request                          |
75 
++-----------------------+----------+----------------------------------------------------------------+
76 
+| language              | string   | ISO code of language and country like en\_US                   |
77 
++-----------------------+----------+----------------------------------------------------------------+
78 
+| api\_key              | string   | api-key if required by engine                                  |
79 
++-----------------------+----------+----------------------------------------------------------------+
80 
+
81 
+example code
84 82 
 ~~~~~~~~~~~~
85 83
86 84 
 .. code:: python
 
@@ -90,21 +88,20 @@ example-code
90 88 
     paging = True
91 89 
     language_support = True
92 90
93 
-doing request
94 
--------------
91 
+making a request
92 
+----------------
95 93
96 
-To perform a search you have to specific at least a url on which the
97 
-request is performing
94 
+To perform a search an URL have to be specified. In addition to
95 
+specifying an URL, arguments can be passed to the query.
98 96
99 97 
 passed arguments
100 98 
 ~~~~~~~~~~~~~~~~
101 99
102 
-This arguments can be used to calculate the search-query. Furthermore,
103 
-some of that parameters are filled with default values which can be
104 
-changed for special purpose.
100 
+These arguments can be used to construct the search query. Furthermore,
101 
+parameters with default value can be redefined for special purposes.
105 102
106 103 
 +----------------------+------------+------------------------------------------------------------------------+
107 
-| argument             | type       | default-value, informations                                            |
104 
+| argument             | type       | default-value, information                                             |
108 105 
 +======================+============+========================================================================+
109 106 
 | url                  | string     | ``''``                                                                 |
110 107 
 +----------------------+------------+------------------------------------------------------------------------+
 
@@ -132,27 +129,27 @@ changed for special purpose.
132 129 
 parsed arguments
133 130 
 ~~~~~~~~~~~~~~~~
134 131
135 
-The function ``def request(query, params):`` is always returning the
136 
-``params`` variable back. Inside searx, the following paramters can be
137 
-used to specific a search-request:
138 
-
139 
-+------------+-----------+----------------------------------------------------------+
140 
-| argument   | type      | information                                              |
141 
-+============+===========+==========================================================+
142 
-| url        | string    | requested url                                            |
143 
-+------------+-----------+----------------------------------------------------------+
144 
-| method     | string    | HTTP request methode                                     |
145 
-+------------+-----------+----------------------------------------------------------+
146 
-| headers    | set       | HTTP header informations                                 |
147 
-+------------+-----------+----------------------------------------------------------+
148 
-| data       | set       | HTTP data informations (parsed if ``method != 'GET'``)   |
149 
-+------------+-----------+----------------------------------------------------------+
150 
-| cookies    | set       | HTTP cookies                                             |
151 
-+------------+-----------+----------------------------------------------------------+
152 
-| verify     | boolean   | Performing SSL-Validity check                            |
153 
-+------------+-----------+----------------------------------------------------------+
154 
-
155 
-example-code
132 
+The function ``def request(query, params):`` always returns the
133 
+``params`` variable. Inside searx, the following paramters can be
134 
+used to specify a search request:
135 
+
136 
++------------+-----------+---------------------------------------------------------+
137 
+| argument   | type      | information                                             |
138 
++============+===========+=========================================================+
139 
+| url        | string    | requested url                                           |
140 
++------------+-----------+---------------------------------------------------------+
141 
+| method     | string    | HTTP request method                                     |
142 
++------------+-----------+---------------------------------------------------------+
143 
+| headers    | set       | HTTP header information                                 |
144 
++------------+-----------+---------------------------------------------------------+
145 
+| data       | set       | HTTP data information (parsed if ``method != 'GET'``)   |
146 
++------------+-----------+---------------------------------------------------------+
147 
+| cookies    | set       | HTTP cookies                                            |
148 
++------------+-----------+---------------------------------------------------------+
149 
+| verify     | boolean   | Performing SSL-Validity check                           |
150 
++------------+-----------+---------------------------------------------------------+
151 
+
152 
+example code
156 153 
 ~~~~~~~~~~~~
157 154
158 155 
 .. code:: python
 
@@ -171,10 +168,10 @@ example-code
171 168
172 169 
         return params
173 170
174 
-returning results
175 
------------------
171 
+returned results
172 
+----------------
176 173
177 
-Searx has the possiblity to return results in different media-types.
174 
+Searx is able to return results of different media-types.
178 175 
 Currently the following media-types are supported:
179 176
180 177 
 -  default
 
@@ -183,8 +180,8 @@ Currently the following media-types are supported:
183 180 
 -  torrent
184 181 
 -  map
185 182
186 
-to set another media-type as default, you must set the parameter
187 
-``template`` to the required type.
183 
+To set another media-type as default, the parameter
184 
+``template`` must be set to the desired type.
188 185
189 186 
 default
190 187 
 ~~~~~~~
 
@@ -246,31 +243,31 @@ videos
246 243 
 torrent
247 244 
 ~~~~~~~
248 245
249 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
250 
-| result-parameter | information                                                                                                                                           |
251 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
252 
-| template         | is set to ```torrent.html```                                                                                                                          |
253 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
254 
-| url              | string, which is representing the url of the result                                                                                                   |
255 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
256 
-| title            | string, which is representing the title of the result                                                                                                 |
257 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
258 
-| content          | string, which is giving a general result-text                                                                                                         |
259 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
260 
-| publishedDate    | [datetime.datetime](https://docs.python.org/2/library/datetime.html#datetime-objects), represent when the result is published _(not implemented yet)_ |
261 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
262 
-| seed             | int, number of seeder                                                                                                                                 |
263 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
264 
-| leech            | int, number of leecher                                                                                                                                |
265 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
266 
-| filesize         | int, size of file in bytes                                                                                                                            |
267 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
268 
-| files            | int, number of files                                                                                                                                  |
269 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
270 
-| magnetlink       | string, which is the [magnetlink](https://en.wikipedia.org/wiki/Magnet_URI_scheme) of the result                                                      |
271 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
272 
-| torrentfile      | string, which is the torrentfile of the result                                                                                                        |
273 
-+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
246 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
247 
+| result-parameter | information                                                                                                                                              |
248 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
249 
+| template         | is set to ```torrent.html```                                                                                                                             |
250 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
251 
+| url              | string, which is representing the url of the result                                                                                                      |
252 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
253 
+| title            | string, which is representing the title of the result                                                                                                    |
254 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
255 
+| content          | string, which is giving a general result-text                                                                                                            |
256 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
257 
+| publishedDate    | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, represent when the result is published *(not implemented yet)* |
258 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
259 
+| seed             | int, number of seeder                                                                                                                                    |
260 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
261 
+| leech            | int, number of leecher                                                                                                                                   |
262 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
263 
+| filesize         | int, size of file in bytes                                                                                                                               |
264 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
265 
+| files            | int, number of files                                                                                                                                     |
266 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
267 
+| magnetlink       | string, which is the `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ of the result                                                      |
268 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
269 
+| torrentfile      | string, which is the torrentfile of the result                                                                                                           |
270 
++------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
274 271
275 272
276 273 
 map