From ea62df1dc0c5206e08efda350d2480a117ad4ede Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 12 Dec 2020 20:31:49 +0100 Subject: [PATCH] [doc] update developer quickstart guide See https://github.com/searx/searx/issues/2369#issuecomment-740652878 Signed-off-by: Markus Heiser --- docs/dev/contribution_guide.rst | 2 +- docs/dev/quickstart.rst | 133 +++++++------------------------- 2 files changed, 29 insertions(+), 106 deletions(-) diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 90b22670..cffbbcae 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -87,7 +87,7 @@ In order to submit a patch, please follow the steps below: - Add yourself to the :origin:`AUTHORS.rst` file. -- Choose meaning full commit messages, read `Conventional Commits`_ +- Choose meaningful commit messages, read `Conventional Commits`_ .. code:: diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index 14af03fa..bb9f4d67 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -4,129 +4,52 @@ Development Quickstart ====================== -.. sidebar:: :ref:`makefile` +.. _npm: https://www.npmjs.com/ - For additional developer purpose there are :ref:`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 ` - - 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``. +Searx loves developers, just clone and start hacking. All the rest is done for +you simply by using :ref:`make `. .. code:: sh - cd ~/myprojects git clone https://github.com/searx/searx.git - cd searx - python3 -m venv searx-ve - . ./searx-ve/bin/activate - ./manage.sh update_dev_packages +Here is how a minimal workflow looks like: -How to run tests -================ +1. *start* hacking +2. *run* your code: :ref:`make run` +3. *test* your code: :ref:`make test` -.. sidebar:: :ref:`make test.unit ` +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. - 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 -==================================== - -.. _less: https://lesscss.org/ -.. _NodeJS: https://nodejs.org - -How to build styles -------------------- - -Less_ is required to build the styles of searx. Less_ can be installed using -either NodeJS_ or Apt. - -.. code:: sh - - sudo -H apt-get install nodejs - 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 - - sudo -H apt-get install nodejs - make node.env - -After installing grunt, the files can be built using the following command: +If you implement themes, you will need to compile styles and JavaScript before +*run*. .. code:: sh make themes +Don't forget to install npm_ first. -Tips for debugging/development -============================== +.. tabs:: -.. sidebar:: :ref:`make run` + .. group-tab:: Ubuntu / debian - Makefile target ``run`` already enables debug option for your developer - session / see :ref:`make run`. + .. code:: sh -Turn on debug logging - 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 `. + sudo -H apt-get install npm -.. sidebar:: :ref:`make test` + .. group-tab:: Arch Linux - Alternatively use the :ref:`make test` targets. + .. code-block:: sh + + sudo -H pacman -S npm + + .. group-tab:: Fedora / RHEL + + .. code-block:: sh + + 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.