devol/searx
1
0
Fork 0
mirror of https://github.com/searx/searx synced 2025-02-23 15:17:46 +01:00
Code Issues Releases Wiki Activity

Merge pull request #467 from kvch/gh-pages

Browse Source 
updated & rewritten contribution guide
This commit is contained in:
Adam Tauber 2015-12-11 12:19:07 +01:00
commit f7a7c4318b
6 changed files with 194 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
_sources/dev/contribution_guide.txt
View File

@ -4,68 +4,93 @@ How to contribute
Prime directives: Privacy, Hackability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Searx has 2 prime directives, privacy-by-design and hackability. The
hackability comes in at least 3 levels:
Searx has two prime directives, privacy-by-design and hackability. The
hackability comes in three levels:
- support for search engines
- plugins for altering search behaviour
- hacking searx itself.
- support of search engines
- plugins to alter search behaviour
- hacking searx itself
Happy hacking. Observe the lack of "world domination" among the
directives, searx has no intentions for wide mass-adoption, rounded
corners, etc. The prime directive: "privacy" - deserves a seperate
chapter, as it's quite uncommon unfortunately, here it goes:
Note the lack of "world domination" among the directives.
Searx has no intention of wide mass-adoption, rounded
corners, etc. The prime directive "privacy" deserves a separate
chapter, as it's quite uncommon unfortunately.
Privacy-by-design
^^^^^^^^^^^^^^^^^
Searx is a privacy-respecting, hackable meta-search engine. It was born
out of the need for a privacy-respecing search facility that can be
expanded easily to maximise both its search and it's privacy protecting
capabilities.
Searx was born out of the need for a privacy-respecting search tool
which can be extended easily to maximize both its search and its
privacy protecting capabilities.
Consequences of Privacy-by-design are that some widely used features
work differently or not by default or at all. If some feature reduces
the privacy perserving aspects of searx, it should by default be
switched of, if implemented at all. There is enough search engines
already out there providing such features. = Since privacy-preservation
is a prime goal, if some feature does reduce the protection of searx and
is implemented, care should be taken to educate the user about the
consequences of choosing to enable this. Further features which
implement widely known features in a manner that protects privacy but
thus deviate from the users expectations should also be explained to the
user. Also if you think that something works weird with searx, maybe
it's because of the tool you use is designed in a way to interfere with
privacy respect, submiting a bugreport to the vendor of the tool that
misbehaves might be a good feedback for the vendor to reconsider his
disrespect towards his customers (e.g. GET vs POST requests in various
browsers).
A few widely used features work differently or turned off by default or not implemented
at all as a consequence of privacy-by-design.
If a feature reduces the privacy preserving aspects of searx, it
should be switched off by default or should not implemented at all.
There are plenty of search engines already providing such features.
If a feature reduces the protection of searx, users must be
informed about the effect of choosing to enable it. Features
that protect privacy but differ from the expectations of the
user should also be explained.
Also, if you think that something works weird with searx,
it's might be because of the tool you use is designed in a way to interfere with
the privacy respect. Submitting a bugreport to the vendor of the tool that
misbehaves might be a good feedback to reconsider the disrespect to
its customers (e.g. GET vs POST requests in various browsers).
Remember the other prime directive of searx is to be hackable, so if the
above privacy concerns do not fancy you, simply fork it.
Happy hacking.
Code
~~~~
Code modifications are accepted in pull requests, don't forget to add
yourself to the AUTHORS file.
In order to submit a patch, please follow the steps below:
Python code follows all the pep8 standards except maximum line width
which is 120 char.
- Follow coding conventions.
Please be sure that the submitted code doesn't break existing tests and
follows coding conventions.
- PEP8 standards apply, except the convention of line length
- Maximum line length is 120 characters
- Check if your code breaks existing tests. If so, update the tests or fix your code.
- If your code can be unit-tested, add unit tests.
- Add yourself to the AUTHORS file.
- Create a pull request.
If new functionality implemented, tests are highly appreciated.
Translation
~~~~~~~~~~~
Translation currently happens on
`transifex <https://transifex.com/projects/p/searx>`__. Please do not
update translation files in the repo.
Translation currently takes place on
`transifex <https://transifex.com/projects/p/searx>`__.
**Please, do not update translation files in the repo.**
Documentation
~~~~~~~~~~~~~
The main place of the documentation is this wiki, updates are welcome.
The documentation is built using Sphinx. So in order to be able to generate the required
files, you have to install it on your system. (It can be installed easily using pip.)
1. Checkout the gh-pages branch.
2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.
3. Build the documentation using Sphinx.
4. Add the updated and created files of these extension:
- .rst
- .html
- .txt
6. Create a pull request.

4
_sources/dev/engine_overview.txt
View File

@ -23,7 +23,7 @@ arguments can be set in the engine file or in the settings file
(normally ``settings.yml``). The arguments in the settings file override
the ones in the engine file.
It does not matter if an options is stored in the engine file or in the
It does not matter if an option is stored in the engine file or in the
settings. However, the standard way is the following:
@ -63,7 +63,7 @@ often overwritten by the settings. If ``None`` is assigned to an option
in the engine file, it has to be redefined in the settings,
otherwise searx will not start with that engine.
The naming of that overrides is arbitrary. But the recommended
The naming of overrides is arbitrary. But the recommended
overrides are the following:
+-----------------------+----------+----------------------------------------------------------------+

98
dev/contribution_guide.html
View File

@ -43,62 +43,80 @@
<h1>How to contribute<a class="headerlink" href="#how-to-contribute" title="Permalink to this headline"></a></h1>
<div class="section" id="prime-directives-privacy-hackability">
<h2>Prime directives: Privacy, Hackability<a class="headerlink" href="#prime-directives-privacy-hackability" title="Permalink to this headline"></a></h2>
<p>Searx has 2 prime directives, privacy-by-design and hackability. The
hackability comes in at least 3 levels:</p>
<p>Searx has two prime directives, privacy-by-design and hackability. The
hackability comes in three levels:</p>
<ul class="simple">
<li>support for search engines</li>
<li>plugins for altering search behaviour</li>
<li>hacking searx itself.</li>
<li>support of search engines</li>
<li>plugins to alter search behaviour</li>
<li>hacking searx itself</li>
</ul>
<p>Happy hacking. Observe the lack of &#8220;world domination&#8221; among the
directives, searx has no intentions for wide mass-adoption, rounded
corners, etc. The prime directive: &#8220;privacy&#8221; - deserves a seperate
chapter, as it&#8217;s quite uncommon unfortunately, here it goes:</p>
<p>Note the lack of &#8220;world domination&#8221; among the directives.
Searx has no intention of wide mass-adoption, rounded
corners, etc. The prime directive &#8220;privacy&#8221; deserves a separate
chapter, as it&#8217;s quite uncommon unfortunately.</p>
<div class="section" id="privacy-by-design">
<h3>Privacy-by-design<a class="headerlink" href="#privacy-by-design" title="Permalink to this headline"></a></h3>
<p>Searx is a privacy-respecting, hackable meta-search engine. It was born
out of the need for a privacy-respecing search facility that can be
expanded easily to maximise both its search and it&#8217;s privacy protecting
capabilities.</p>
<p>Consequences of Privacy-by-design are that some widely used features
work differently or not by default or at all. If some feature reduces
the privacy perserving aspects of searx, it should by default be
switched of, if implemented at all. There is enough search engines
already out there providing such features. =&nbsp;Since privacy-preservation
is a prime goal, if some feature does reduce the protection of searx and
is implemented, care should be taken to educate the user about the
consequences of choosing to enable this. Further features which
implement widely known features in a manner that protects privacy but
thus deviate from the users expectations should also be explained to the
user. Also if you think that something works weird with searx, maybe
it&#8217;s because of the tool you use is designed in a way to interfere with
privacy respect, submiting a bugreport to the vendor of the tool that
misbehaves might be a good feedback for the vendor to reconsider his
disrespect towards his customers (e.g. GET vs POST requests in various
browsers).</p>
<p>Searx was born out of the need for a privacy-respecting search tool
which can be extended easily to maximize both its search and its
privacy protecting capabilities.</p>
<p>A few widely used features work differently or turned off by default or not implemented
at all as a consequence of privacy-by-design.</p>
<p>If a feature reduces the privacy preserving aspects of searx, it
should be switched off by default or should not implemented at all.
There are plenty of search engines already providing such features.
If a feature reduces the protection of searx, users must be
informed about the effect of choosing to enable it. Features
that protect privacy but differ from the expectations of the
user should also be explained.</p>
<p>Also, if you think that something works weird with searx,
it&#8217;s might be because of the tool you use is designed in a way to interfere with
the privacy respect. Submitting a bugreport to the vendor of the tool that
misbehaves might be a good feedback to reconsider the disrespect to
its customers (e.g. GET vs POST requests in various browsers).</p>
<p>Remember the other prime directive of searx is to be hackable, so if the
above privacy concerns do not fancy you, simply fork it.</p>
<p>Happy hacking.</p>
</div>
</div>
<div class="section" id="code">
<h2>Code<a class="headerlink" href="#code" title="Permalink to this headline"></a></h2>
<p>Code modifications are accepted in pull requests, don&#8217;t forget to add
yourself to the AUTHORS file.</p>
<p>Python code follows all the pep8 standards except maximum line width
which is 120 char.</p>
<p>Please be sure that the submitted code doesn&#8217;t break existing tests and
follows coding conventions.</p>
<p>If new functionality implemented, tests are highly appreciated.</p>
<p>In order to submit a patch, please follow the steps below:</p>
<ul class="simple">
<li>Follow coding conventions.<ul>
<li>PEP8 standards apply, except the convention of line length</li>
<li>Maximum line length is 120 characters</li>
</ul>
</li>
<li>Check if your code breaks existing tests. If so, update the tests or fix your code.</li>
<li>If your code can be unit-tested, add unit tests.</li>
<li>Add yourself to the AUTHORS file.</li>
<li>Create a pull request.</li>
</ul>
</div>
<div class="section" id="translation">
<h2>Translation<a class="headerlink" href="#translation" title="Permalink to this headline"></a></h2>
<p>Translation currently happens on
<a class="reference external" href="https://transifex.com/projects/p/searx">transifex</a>. Please do not
update translation files in the repo.</p>
<p>Translation currently takes place on
<a class="reference external" href="https://transifex.com/projects/p/searx">transifex</a>.</p>
<p><strong>Please, do not update translation files in the repo.</strong></p>
</div>
<div class="section" id="documentation">
<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline"></a></h2>
<p>The main place of the documentation is this wiki, updates are welcome.</p>
<p>The documentation is built using Sphinx. So in order to be able to generate the required
files, you have to install it on your system. (It can be installed easily using pip.)</p>
<ol class="arabic simple">
<li>Checkout the gh-pages branch.</li>
<li>Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.</li>
<li>Build the documentation using Sphinx.</li>
<li>Add the updated and created files of these extension:<ul>
<li>.rst</li>
<li>.html</li>
<li>.txt</li>
</ul>
</li>
</ol>
<ol class="arabic simple" start="6">
<li>Create a pull request.</li>
</ol>
</div>
</div>

4
dev/engine_overview.html
View File

@ -82,7 +82,7 @@ external search engines. Adapters are stored under the folder
arguments can be set in the engine file or in the settings file
(normally <code class="docutils literal"><span class="pre">settings.yml</span></code>). The arguments in the settings file override
the ones in the engine file.</p>
<p>It does not matter if an options is stored in the engine file or in the
<p>It does not matter if an option is stored in the engine file or in the
settings. However, the standard way is the following:</p>
<div class="section" id="engine-file">
<h3><a class="toc-backref" href="#id4">engine file</a><a class="headerlink" href="#engine-file" title="Permalink to this headline"></a></h3>
@ -154,7 +154,7 @@ settings. However, the standard way is the following:</p>
often overwritten by the settings. If <code class="docutils literal"><span class="pre">None</span></code> is assigned to an option
in the engine file, it has to be redefined in the settings,
otherwise searx will not start with that engine.</p>
<p>The naming of that overrides is arbitrary. But the recommended
<p>The naming of overrides is arbitrary. But the recommended
overrides are the following:</p>
<table border="1" class="docutils">
<colgroup>

105
docs/dev/contribution_guide.rst
View File

@ -4,68 +4,93 @@ How to contribute
Prime directives: Privacy, Hackability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Searx has 2 prime directives, privacy-by-design and hackability. The
hackability comes in at least 3 levels:
Searx has two prime directives, privacy-by-design and hackability. The
hackability comes in three levels:
- support for search engines
- plugins for altering search behaviour
- hacking searx itself.
- support of search engines
- plugins to alter search behaviour
- hacking searx itself
Happy hacking. Observe the lack of "world domination" among the
directives, searx has no intentions for wide mass-adoption, rounded
corners, etc. The prime directive: "privacy" - deserves a seperate
chapter, as it's quite uncommon unfortunately, here it goes:
Note the lack of "world domination" among the directives.
Searx has no intention of wide mass-adoption, rounded
corners, etc. The prime directive "privacy" deserves a separate
chapter, as it's quite uncommon unfortunately.
Privacy-by-design
^^^^^^^^^^^^^^^^^
Searx is a privacy-respecting, hackable meta-search engine. It was born
out of the need for a privacy-respecing search facility that can be
expanded easily to maximise both its search and it's privacy protecting
capabilities.
Searx was born out of the need for a privacy-respecting search tool
which can be extended easily to maximize both its search and its
privacy protecting capabilities.
Consequences of Privacy-by-design are that some widely used features
work differently or not by default or at all. If some feature reduces
the privacy perserving aspects of searx, it should by default be
switched of, if implemented at all. There is enough search engines
already out there providing such features. = Since privacy-preservation
is a prime goal, if some feature does reduce the protection of searx and
is implemented, care should be taken to educate the user about the
consequences of choosing to enable this. Further features which
implement widely known features in a manner that protects privacy but
thus deviate from the users expectations should also be explained to the
user. Also if you think that something works weird with searx, maybe
it's because of the tool you use is designed in a way to interfere with
privacy respect, submiting a bugreport to the vendor of the tool that
misbehaves might be a good feedback for the vendor to reconsider his
disrespect towards his customers (e.g. GET vs POST requests in various
browsers).
A few widely used features work differently or turned off by default or not implemented
at all as a consequence of privacy-by-design.
If a feature reduces the privacy preserving aspects of searx, it
should be switched off by default or should not implemented at all.
There are plenty of search engines already providing such features.
If a feature reduces the protection of searx, users must be
informed about the effect of choosing to enable it. Features
that protect privacy but differ from the expectations of the
user should also be explained.
Also, if you think that something works weird with searx,
it's might be because of the tool you use is designed in a way to interfere with
the privacy respect. Submitting a bugreport to the vendor of the tool that
misbehaves might be a good feedback to reconsider the disrespect to
its customers (e.g. GET vs POST requests in various browsers).
Remember the other prime directive of searx is to be hackable, so if the
above privacy concerns do not fancy you, simply fork it.
Happy hacking.
Code
~~~~
Code modifications are accepted in pull requests, don't forget to add
yourself to the AUTHORS file.
In order to submit a patch, please follow the steps below:
Python code follows all the pep8 standards except maximum line width
which is 120 char.
- Follow coding conventions.
Please be sure that the submitted code doesn't break existing tests and
follows coding conventions.
- PEP8 standards apply, except the convention of line length
- Maximum line length is 120 characters
- Check if your code breaks existing tests. If so, update the tests or fix your code.
- If your code can be unit-tested, add unit tests.
- Add yourself to the AUTHORS file.
- Create a pull request.
If new functionality implemented, tests are highly appreciated.
Translation
~~~~~~~~~~~
Translation currently happens on
`transifex <https://transifex.com/projects/p/searx>`__. Please do not
update translation files in the repo.
Translation currently takes place on
`transifex <https://transifex.com/projects/p/searx>`__.
**Please, do not update translation files in the repo.**
Documentation
~~~~~~~~~~~~~
The main place of the documentation is this wiki, updates are welcome.
The documentation is built using Sphinx. So in order to be able to generate the required
files, you have to install it on your system. (It can be installed easily using pip.)
1. Checkout the gh-pages branch.
2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.
3. Build the documentation using Sphinx.
4. Add the updated and created files of these extension:
- .rst
- .html
- .txt
6. Create a pull request.

4
docs/dev/engine_overview.rst
View File

@ -23,7 +23,7 @@ arguments can be set in the engine file or in the settings file
(normally ``settings.yml``). The arguments in the settings file override
the ones in the engine file.
It does not matter if an options is stored in the engine file or in the
It does not matter if an option is stored in the engine file or in the
settings. However, the standard way is the following:
@ -63,7 +63,7 @@ often overwritten by the settings. If ``None`` is assigned to an option
in the engine file, it has to be redefined in the settings,
otherwise searx will not start with that engine.
The naming of that overrides is arbitrary. But the recommended
The naming of overrides is arbitrary. But the recommended
overrides are the following:
+-----------------------+----------+----------------------------------------------------------------+