Loading docs/dev/contribution_guide.rst +1 −1 Original line number Original line Diff line number Diff line Loading @@ -87,7 +87,7 @@ In order to submit a patch, please follow the steps below: - Add yourself to the :origin:`AUTHORS.rst` file. - Add yourself to the :origin:`AUTHORS.rst` file. - Choose meaning full commit messages, read `Conventional Commits`_ - Choose meaningful commit messages, read `Conventional Commits`_ .. code:: .. code:: Loading docs/dev/quickstart.rst +25 −102 Original line number Original line Diff line number Diff line Loading @@ -4,129 +4,52 @@ Development Quickstart Development Quickstart ====================== ====================== .. sidebar:: :ref:`makefile` .. _npm: https://www.npmjs.com/ For additional developer purpose there are :ref:`makefile`. Searx loves developers, just clone and start hacking. All the rest is done for you simply by using :ref:`make <makefile>`. This quickstart guide gets your environment set up with searx. Furthermore, it gives a short introduction to the ``manage.sh`` script. How to setup your development environment ========================================= .. sidebar:: :ref:`make pyenv <make pyenv>` Alternatively use the :ref:`make pyenv`. First, clone the source code of searx to the desired folder. In this case the source is cloned to ``~/myprojects/searx``. Then create and activate the searx-ve virtualenv and install the required packages using ``manage.sh``. .. code:: sh .. code:: sh cd ~/myprojects git clone https://github.com/searx/searx.git git clone https://github.com/searx/searx.git cd searx python3 -m venv searx-ve . ./searx-ve/bin/activate ./manage.sh update_dev_packages How to run tests ================ .. sidebar:: :ref:`make test.unit <make test>` Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets. Tests can be run using the ``manage.sh`` script. Following tests and checks are available: - Unit tests - Selenium tests - PEP8 validation - Unit test coverage check For example unit tests are run with the command below: .. code:: sh ./manage.sh unit_tests For further test options, please consult the help of the ``manage.sh`` script or read :ref:`make test`. How to compile styles and javascript Here is how a minimal workflow looks like: ==================================== .. _less: https://lesscss.org/ 1. *start* hacking .. _NodeJS: https://nodejs.org 2. *run* your code: :ref:`make run` 3. *test* your code: :ref:`make test` How to build styles If you think at some point something fails, go back to *start*. Otherwise, ------------------- choose a meaningful commit message and we are happy to receive your pull request. To not end in *wild west* we have some directives, please pay attention to our ":ref:`how to contribute`" guideline. Less_ is required to build the styles of searx. Less_ can be installed using If you implement themes, you will need to compile styles and JavaScript before either NodeJS_ or Apt. *run*. .. code:: sh .. code:: sh sudo -H apt-get install nodejs make themes sudo -H npm install -g less OR .. code:: sh sudo -H apt-get install node-less After satisfying the requirements styles can be build using ``manage.sh`` .. code:: sh ./manage.sh styles How to build the source of the themes ===================================== .. _grunt: https://gruntjs.com/ Grunt_ must be installed in order to build the javascript sources. It depends on NodeJS, so first Node has to be installed. .. code:: sh Don't forget to install npm_ first. sudo -H apt-get install nodejs .. tabs:: make node.env After installing grunt, the files can be built using the following command: .. group-tab:: Ubuntu / debian .. code:: sh .. code:: sh make themes sudo -H apt-get install npm Tips for debugging/development .. group-tab:: Arch Linux ============================== .. sidebar:: :ref:`make run` .. code-block:: sh Makefile target ``run`` already enables debug option for your developer sudo -H pacman -S npm session / see :ref:`make run`. Turn on debug logging .. group-tab:: Fedora / RHEL Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea to turn on debug logging. When debug logging is enabled a stack trace appears, instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting ``debug: False`` to ``debug: True`` in :origin:`settings.yml <searx/settings.yml>`. .. sidebar:: :ref:`make test` .. code-block:: sh Alternatively use the :ref:`make test` targets. sudo -H dnf install npm Run ``./manage.sh tests`` before creating a PR. Failing build on Travis is common because of PEP8 checks. So a new commit must be created containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run locally before creating a PR. Loading
docs/dev/contribution_guide.rst +1 −1 Original line number Original line Diff line number Diff line Loading @@ -87,7 +87,7 @@ In order to submit a patch, please follow the steps below: - Add yourself to the :origin:`AUTHORS.rst` file. - Add yourself to the :origin:`AUTHORS.rst` file. - Choose meaning full commit messages, read `Conventional Commits`_ - Choose meaningful commit messages, read `Conventional Commits`_ .. code:: .. code:: Loading
docs/dev/quickstart.rst +25 −102 Original line number Original line Diff line number Diff line Loading @@ -4,129 +4,52 @@ Development Quickstart Development Quickstart ====================== ====================== .. sidebar:: :ref:`makefile` .. _npm: https://www.npmjs.com/ For additional developer purpose there are :ref:`makefile`. Searx loves developers, just clone and start hacking. All the rest is done for you simply by using :ref:`make <makefile>`. This quickstart guide gets your environment set up with searx. Furthermore, it gives a short introduction to the ``manage.sh`` script. How to setup your development environment ========================================= .. sidebar:: :ref:`make pyenv <make pyenv>` Alternatively use the :ref:`make pyenv`. First, clone the source code of searx to the desired folder. In this case the source is cloned to ``~/myprojects/searx``. Then create and activate the searx-ve virtualenv and install the required packages using ``manage.sh``. .. code:: sh .. code:: sh cd ~/myprojects git clone https://github.com/searx/searx.git git clone https://github.com/searx/searx.git cd searx python3 -m venv searx-ve . ./searx-ve/bin/activate ./manage.sh update_dev_packages How to run tests ================ .. sidebar:: :ref:`make test.unit <make test>` Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets. Tests can be run using the ``manage.sh`` script. Following tests and checks are available: - Unit tests - Selenium tests - PEP8 validation - Unit test coverage check For example unit tests are run with the command below: .. code:: sh ./manage.sh unit_tests For further test options, please consult the help of the ``manage.sh`` script or read :ref:`make test`. How to compile styles and javascript Here is how a minimal workflow looks like: ==================================== .. _less: https://lesscss.org/ 1. *start* hacking .. _NodeJS: https://nodejs.org 2. *run* your code: :ref:`make run` 3. *test* your code: :ref:`make test` How to build styles If you think at some point something fails, go back to *start*. Otherwise, ------------------- choose a meaningful commit message and we are happy to receive your pull request. To not end in *wild west* we have some directives, please pay attention to our ":ref:`how to contribute`" guideline. Less_ is required to build the styles of searx. Less_ can be installed using If you implement themes, you will need to compile styles and JavaScript before either NodeJS_ or Apt. *run*. .. code:: sh .. code:: sh sudo -H apt-get install nodejs make themes sudo -H npm install -g less OR .. code:: sh sudo -H apt-get install node-less After satisfying the requirements styles can be build using ``manage.sh`` .. code:: sh ./manage.sh styles How to build the source of the themes ===================================== .. _grunt: https://gruntjs.com/ Grunt_ must be installed in order to build the javascript sources. It depends on NodeJS, so first Node has to be installed. .. code:: sh Don't forget to install npm_ first. sudo -H apt-get install nodejs .. tabs:: make node.env After installing grunt, the files can be built using the following command: .. group-tab:: Ubuntu / debian .. code:: sh .. code:: sh make themes sudo -H apt-get install npm Tips for debugging/development .. group-tab:: Arch Linux ============================== .. sidebar:: :ref:`make run` .. code-block:: sh Makefile target ``run`` already enables debug option for your developer sudo -H pacman -S npm session / see :ref:`make run`. Turn on debug logging .. group-tab:: Fedora / RHEL Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea to turn on debug logging. When debug logging is enabled a stack trace appears, instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting ``debug: False`` to ``debug: True`` in :origin:`settings.yml <searx/settings.yml>`. .. sidebar:: :ref:`make test` .. code-block:: sh Alternatively use the :ref:`make test` targets. sudo -H dnf install npm Run ``./manage.sh tests`` before creating a PR. Failing build on Travis is common because of PEP8 checks. So a new commit must be created containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run locally before creating a PR.
