git.iko.soy/searx
on master help sign in
Merge pull request #2380 from return42/dev-quickstart
17fdfb6Alexandre Flament
docs/dev/contribution_guide.rst+1−1
compare with master
unifiedsplit
@@ -87,7 +87,7 @@ In order to submit a patch, please follow the steps below:
87
87
88- Add yourself to the :origin:`AUTHORS.rst` file.
88- Add yourself to the :origin:`AUTHORS.rst` file.
89
89
90−- Choose meaning full commit messages, read `Conventional Commits`_
90+- Choose meaningful commit messages, read `Conventional Commits`_
91
91
92 .. code::
92 .. code::
93
93
docs/dev/quickstart.rst+25−102
@@ -4,129 +4,52 @@
4Development Quickstart
4Development Quickstart
5======================
5======================
6
6
7−.. sidebar:: :ref:`makefile`
7+.. _npm: https://www.npmjs.com/
8
8
9− For additional developer purpose there are :ref:`makefile`.
9+Searx loves developers, just clone and start hacking. All the rest is done for
10−
10+you simply by using :ref:`make <makefile>`.
11−This quickstart guide gets your environment set up with searx. Furthermore, it
12−gives a short introduction to the ``manage.sh`` script.
13−
14−How to setup your development environment
15−=========================================
16−
17−.. sidebar:: :ref:`make pyenv <make pyenv>`
18−
19− Alternatively use the :ref:`make pyenv`.
20−
21−First, clone the source code of searx to the desired folder. In this case the
22−source is cloned to ``~/myprojects/searx``. Then create and activate the
23−searx-ve virtualenv and install the required packages using ``manage.sh``.
24
11
25.. code:: sh
12.. code:: sh
26
13
27− cd ~/myprojects
28 git clone https://github.com/searx/searx.git
14 git clone https://github.com/searx/searx.git
29− cd searx
30− python3 -m venv searx-ve
31− . ./searx-ve/bin/activate
32− ./manage.sh update_dev_packages
33−
34−
35−How to run tests
36−================
37−
38−.. sidebar:: :ref:`make test.unit <make test>`
39−
40− Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets.
41−
42−Tests can be run using the ``manage.sh`` script. Following tests and checks are
43−available:
44−
45−- Unit tests
46−- Selenium tests
47−- PEP8 validation
48−- Unit test coverage check
49−
50−For example unit tests are run with the command below:
51−
52−.. code:: sh
53−
54− ./manage.sh unit_tests
55−
56−For further test options, please consult the help of the ``manage.sh`` script or
57−read :ref:`make test`.
58−
59
15
60−How to compile styles and javascript
16+Here is how a minimal workflow looks like:
61−====================================
62
17
63−.. _less: https://lesscss.org/
18+1. *start* hacking
64−.. _NodeJS: https://nodejs.org
19+2. *run* your code: :ref:`make run`
20+3. *test* your code: :ref:`make test`
65
21
66−How to build styles
22+If you think at some point something fails, go back to *start*. Otherwise,
67−-------------------
23+choose a meaningful commit message and we are happy to receive your pull
24+request. To not end in *wild west* we have some directives, please pay attention
25+to our ":ref:`how to contribute`" guideline.
68
26
69−Less_ is required to build the styles of searx. Less_ can be installed using
27+If you implement themes, you will need to compile styles and JavaScript before
70−either NodeJS_ or Apt.
28+*run*.
71
29
72.. code:: sh
30.. code:: sh
73
31
74− sudo -H apt-get install nodejs
32+ make themes
75− sudo -H npm install -g less
76−
77−OR
78−
79−.. code:: sh
80−
81− sudo -H apt-get install node-less
82−
83−After satisfying the requirements styles can be build using ``manage.sh``
84−
85−.. code:: sh
86−
87− ./manage.sh styles
88−
89−
90−How to build the source of the themes
91−=====================================
92−
93−.. _grunt: https://gruntjs.com/
94−
95−Grunt_ must be installed in order to build the javascript sources. It depends on
96−NodeJS, so first Node has to be installed.
97−
98−.. code:: sh
99
33
100− sudo -H apt-get install nodejs
34+Don't forget to install npm_ first.
101− make node.env
102
35
103−After installing grunt, the files can be built using the following command:
36+.. tabs::
104
37
105−.. code:: sh
38+ .. group-tab:: Ubuntu / debian
106
39
107− make themes
40+ .. code:: sh
108
41
42+ sudo -H apt-get install npm
109
43
110−Tips for debugging/development
44+ .. group-tab:: Arch Linux
111−==============================
112
45
113−.. sidebar:: :ref:`make run`
46+ .. code-block:: sh
114
47
115− Makefile target ``run`` already enables debug option for your developer
48+ sudo -H pacman -S npm
116− session / see :ref:`make run`.
117
49
118−Turn on debug logging
50+ .. group-tab:: Fedora / RHEL
119− Whether you are working on a new engine or trying to eliminate a bug, it is
120− always a good idea to turn on debug logging. When debug logging is enabled a
121− stack trace appears, instead of the cryptic ``Internal Server Error``
122− message. It can be turned on by setting ``debug: False`` to ``debug: True`` in
123− :origin:`settings.yml <searx/settings.yml>`.
124
51
125−.. sidebar:: :ref:`make test`
52+ .. code-block:: sh
126
53
127− Alternatively use the :ref:`make test` targets.
54+ sudo -H dnf install npm
128
55
129−Run ``./manage.sh tests`` before creating a PR.
130− Failing build on Travis is common because of PEP8 checks. So a new commit
131− must be created containing these format fixes. This phase can be skipped if
132− ``./manage.sh tests`` is run locally before creating a PR.