Merge pull request #467 from kvch/gh-pages

updated & rewritten contribution guide

docs/dev/contribution_guide.rst

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

docs/dev/engine_overview.rst

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