git.iko.soy/searx
on 07c8ca8 help sign in
searx/docs/dev/contribution_guide.rst
154 lines 4.4 kB history raw
1.. _how to contribute:
3=================
4How to contribute
5=================
7Prime directives: Privacy, Hackability
8======================================
10Searx has two prime directives, **privacy-by-design and hackability** . The
11hackability comes in three levels:
13- support of search engines
14- plugins to alter search behaviour
15- hacking searx itself
17Note the lack of "world domination" among the directives. Searx has no
18intention of wide mass-adoption, rounded corners, etc. The prime directive
19"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
21Privacy-by-design
22-----------------
24Searx was born out of the need for a **privacy-respecting** search tool which
25can be extended easily to maximize both, its search and its privacy protecting
26capabilities.
28A few widely used features work differently or turned off by default or not
29implemented at all **as a consequence of privacy-by-design**.
31If a feature reduces the privacy preserving aspects of searx, it should be
32switched off by default or should not implemented at all. There are plenty of
33search engines already providing such features. If a feature reduces the
34protection of searx, users must be informed about the effect of choosing to
35enable it. Features that protect privacy but differ from the expectations of
36the user should also be explained.
38Also, if you think that something works weird with searx, it's might be because
39of the tool you use is designed in a way to interfere with the privacy respect.
40Submitting a bugreport to the vendor of the tool that misbehaves might be a good
41feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
42requests in various browsers).
44Remember the other prime directive of searx is to be hackable, so if the above
45privacy concerns do not fancy you, simply fork it.
47 *Happy hacking.*
49Code
50====
52.. _PEP8: https://www.python.org/dev/peps/pep-0008/
55In order to submit a patch, please follow the steps below:
57- Follow coding conventions.
59 - PEP8_ standards apply, except the convention of line length
60 - Maximum line length is 120 characters
62- Check if your code breaks existing tests. If so, update the tests or fix your
63 code.
65- If your code can be unit-tested, add unit tests.
67- Add yourself to the :origin:`AUTHORS.rst` file.
69- Create a pull request.
71For more help on getting started with searx development, see :ref:`devquickstart`.
74Translation
75===========
77Translation currently takes place on :ref:`transifex <translation>`.
79.. caution::
81 Please, do not update translation files in the repo.
84.. _contrib docs:
86Documentation
87=============
89.. _Sphinx: http://www.sphinx-doc.org
90.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
92.. sidebar:: The reST sources
94 has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
96The documentation is built using Sphinx_. So in order to be able to generate
97the required files, you have to install it on your system. Much easier, use
98our :ref:`makefile`.
100Here is an example which makes a complete rebuild:
102.. code:: sh
104 $ make docs-clean docs
105 ...
106 The HTML pages are in dist/docs.
108.. _make docs-live:
110live build
111----------
113.. sidebar:: docs-clean
115 It is recommended to assert a complete rebuild before deploying (use
116 ``docs-clean``).
118Live build is like WYSIWYG. If you want to edit the documentation, its
119recommended to use. The Makefile target ``docs-live`` builds the docs, opens
120URL in your favorite browser and rebuilds every time a reST file has been
121changed.
123.. code:: sh
125 $ make docs-live
126 ...
127 The HTML pages are in dist/docs.
128 ... Serving on http://0.0.0.0:8080
129 ... Start watching changes
132.. _deploy on github.io:
134deploy on github.io
135-------------------
137To deploy documentation at :docs:`github.io <.>` use Makefile target
138:ref:`make gh-pages`, which will builds the documentation, clones searx into a sub
139folder ``gh-pages``, cleans it, copies the doc build into and runs all the
140needed git add, commit and push:
142.. code:: sh
144 $ make docs-clean gh-pages
145 ...
146 SPHINX docs --> file://<...>/dist/docs
147 The HTML pages are in dist/docs.
148 ...
149 Cloning into 'gh-pages' ...
150 ...
151 cd gh-pages; git checkout gh-pages >/dev/null
152 Switched to a new branch 'gh-pages'
153 ...
154 doc available at --> https://asciimoo.github.io/searx