From 016ab5c1e87fa86b5e618616e1dd9d49d880c506 Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Mon, 1 Feb 2016 21:28:13 +0100 Subject: add development quickstart --- docs/dev/quickstart.rst | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/dev/quickstart.rst (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst new file mode 100644 index 000000000..edca8af5e --- /dev/null +++ b/docs/dev/quickstart.rst @@ -0,0 +1,90 @@ +Development Quickstart +---------------------- + +This quickstart guide gets your environment set up with searx. Furthermore, it gives a +short introduction to the new manage.sh script. + +How to setup your development environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 + + cd ~/myprojects + git clone https://github.com/asciimoo/searx.git + cd searx + virtualenv searx-ve + . ./searx-ve/bin/activate + ./manage.sh update_dev_packages + + +How to run tests +~~~~~~~~~~~~~~~~ + +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. + + +How to compile styles and javascript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 apt-get install nodejs + sudo npm install -g less + + +OR + +.. code:: sh + + sudo 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 oscar theme +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 apt-get install nodejs + sudo npm install -g grunt-cli + +After installing grunt, the files can be built using the following command: + +.. code:: sh + + ./manage.sh build_grunt -- cgit v1.2.3 From 9c56154cfe121c6b89f48dd6b9af4e5e029d8a6e Mon Sep 17 00:00:00 2001 From: Noemi Vanyi Date: Thu, 21 Apr 2016 13:15:04 +0200 Subject: add dev tips to quickstart --- docs/dev/quickstart.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index edca8af5e..92ef62385 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -1,3 +1,5 @@ +.. _devquickstart: + Development Quickstart ---------------------- @@ -88,3 +90,19 @@ After installing grunt, the files can be built using the following command: .. code:: sh ./manage.sh build_grunt + + + +Tips for debugging/development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. 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 settings.yml. + +2. 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. -- cgit v1.2.3 From 94af140318338ab6e7b064b3b26b5fb45523d17a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9o=20Bourrel?= Date: Thu, 30 Aug 2018 11:14:03 +0200 Subject: Update quickstart.rst Rename `build_grunt` to `grunt_build` as in manage.sh --- docs/dev/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index 92ef62385..e7d4baf46 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -89,7 +89,7 @@ After installing grunt, the files can be built using the following command: .. code:: sh - ./manage.sh build_grunt + ./manage.sh grunt_build -- cgit v1.2.3 From e9fff4fde6d7a8bec3fae087d2afe1fce2145f22 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 12 Dec 2019 19:20:56 +0100 Subject: doc: proofread of the all reST sources (no content change) Normalize reST sources with best practice and KISS in mind. to name a few points: - simplify reST tables - make use of ``literal`` markup for monospace rendering - fix code-blocks for better rendering in HTML - normalize section header markup - limit all lines to a maximum of 79 characters - add option -H to the sudo command used in code blocks - drop useless indentation of lists - ... [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Signed-off-by: Markus Heiser --- docs/dev/quickstart.rst | 92 +++++++++++++++++++++++++------------------------ 1 file changed, 47 insertions(+), 45 deletions(-) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index e7d4baf46..a4a37a266 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -1,17 +1,18 @@ .. _devquickstart: +====================== Development Quickstart ----------------------- +====================== -This quickstart guide gets your environment set up with searx. Furthermore, it gives a -short introduction to the new manage.sh script. +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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================= -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. +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 @@ -24,85 +25,86 @@ virtualenv and install the required packages using manage.sh. How to run tests -~~~~~~~~~~~~~~~~ +================ -Tests can be run using the manage.sh script. - -Following tests and checks are available: +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 + ./manage.sh unit_tests -For further test options, please consult the help of the manage.sh script. +For further test options, please consult the help of the ``manage.sh`` script. How to compile styles and javascript -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +==================================== + +.. _less: http://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. +Less_ is required to build the styles of searx. Less_ can be installed using +either NodeJS_ or Apt. .. code:: sh - sudo apt-get install nodejs - sudo npm install -g less - + sudo -H apt-get install nodejs + sudo -H npm install -g less OR .. code:: sh - sudo apt-get install node-less + sudo -H apt-get install node-less -After satisfying the requirements styles can be build using manage.sh +After satisfying the requirements styles can be build using ``manage.sh`` .. code:: sh - ./manage.sh styles + ./manage.sh styles How to build the source of the oscar theme -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +========================================== -Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first -Node has to be installed. +.. _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 apt-get install nodejs - sudo npm install -g grunt-cli + sudo -H apt-get install nodejs + sudo -H npm install -g grunt-cli -After installing grunt, the files can be built using the following command: +After installing grunt, the files can be built using the following command: .. code:: sh - ./manage.sh grunt_build - + ./manage.sh grunt_build Tips for debugging/development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. 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 settings.yml. - -2. 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. +============================== + +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 `. + +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. -- cgit v1.2.3 From f09459b98ae877d7dfd40d85c0edf058c65913d5 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 18 Dec 2019 16:11:05 +0100 Subject: doc: describe Makefile targets With the aim to simplify development cycles, started with PR #1756 a Makefile based boilerplate was added. This patch adds the missing developer documentation. Signed-off-by: Markus Heiser --- docs/dev/quickstart.rst | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index a4a37a266..e40772b3b 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -4,15 +4,23 @@ Development Quickstart ====================== +.. sidebar:: :ref:`makefile` + + 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-ve virtualenv and install the required packages using ``manage.sh``. .. code:: sh @@ -27,6 +35,10 @@ searx-ve virtualenv and install the required packages using manage.sh. How to run tests ================ +.. sidebar:: :ref:`make test.unit ` + + 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: @@ -41,7 +53,8 @@ For example unit tests are run with the command below: ./manage.sh unit_tests -For further test options, please consult the help of the ``manage.sh`` script. +For further test options, please consult the help of the ``manage.sh`` script or +read :ref:`make test`. How to compile styles and javascript @@ -97,6 +110,11 @@ After installing grunt, the files can be built using the following command: Tips for debugging/development ============================== +.. sidebar:: :ref:`make run` + + Makefile target ``run`` already enables debug option for your developer + session / see :ref:`make run`. + 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 @@ -104,6 +122,10 @@ Turn on debug logging message. It can be turned on by setting ``debug: False`` to ``debug: True`` in :origin:`settings.yml `. +.. sidebar:: :ref:`make test` + + Alternatively use the :ref:`make test` targets. + 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 -- cgit v1.2.3 From 757ebb5d9fdc24757f199e52575f32f6faf091b3 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 25 Mar 2020 14:09:47 +0100 Subject: [fix] brands: add variables from build env to grunt process We have some variables in the build environment which are also needed in the grunt process when building themes. Theses variables are relavant if one creates a fork with its own branding. We treat these variables under the term 'brands'. Signed-off-by: Markus Heiser --- docs/dev/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index e40772b3b..cb079a753 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -87,8 +87,8 @@ After satisfying the requirements styles can be build using ``manage.sh`` ./manage.sh styles -How to build the source of the oscar theme -========================================== +How to build the source of the themes +===================================== .. _grunt: https://gruntjs.com/ @@ -104,7 +104,7 @@ After installing grunt, the files can be built using the following command: .. code:: sh - ./manage.sh grunt_build + make themes Tips for debugging/development -- cgit v1.2.3 From d471ec86dd72cfae80bdaf72b1ed266b1a8cada7 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 25 Mar 2020 16:38:52 +0100 Subject: Makefile: add target node.env - download & install npm dependencies Signed-off-by: Markus Heiser --- docs/dev/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/quickstart.rst') diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index cb079a753..a786eda63 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -98,7 +98,7 @@ NodeJS, so first Node has to be installed. .. code:: sh sudo -H apt-get install nodejs - sudo -H npm install -g grunt-cli + make node.env After installing grunt, the files can be built using the following command: -- cgit v1.2.3