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.
 
-Consequences of Privacy-by-design are that some widely used features
+A few widely used features work differently or turned off by default or not implemented
-work differently or not by default or at all. If some feature reduces
+at all as a consequence of privacy-by-design.
-the privacy perserving aspects of searx, it should by default be
+
-switched of, if implemented at all. There is enough search engines
+If a feature reduces the privacy preserving aspects of searx, it
-already out there providing such features. = Since privacy-preservation
+should be switched off by default or should not implemented at all.
-is a prime goal, if some feature does reduce the protection of searx and
+There are plenty of search engines already providing such features.
-is implemented, care should be taken to educate the user about the
+If a feature reduces the protection of searx, users must be
-consequences of choosing to enable this. Further features which
+informed about the effect of choosing to enable it. Features
-implement widely known features in a manner that protects privacy but
+that protect privacy but differ from the expectations of the
-thus deviate from the users expectations should also be explained to the
+user should also be explained.
-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
+Also, if you think that something works weird with searx,
-privacy respect, submiting a bugreport to the vendor of the tool that
+it's might be because of the tool you use is designed in a way to interfere with
-misbehaves might be a good feedback for the vendor to reconsider his
+the privacy respect. Submitting a bugreport to the vendor of the tool that
-disrespect towards his customers (e.g. GET vs POST requests in various
+misbehaves might be a good feedback to reconsider the disrespect to
-browsers).
+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
+In order to submit a patch, please follow the steps below:
-yourself to the AUTHORS file.
 
-Python code follows all the pep8 standards except maximum line width
+- Follow coding conventions.
-which is 120 char.
 
-Please be sure that the submitted code doesn't break existing tests and
+  - PEP8 standards apply, except the convention of line length
-follows coding conventions.
+
+  - 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
+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:
 
 +-----------------------+----------+----------------------------------------------------------------+