@@ -0,0 +1,217 @@
1+.. _makefile:
2+
3+================
4+Makefile Targets
5+================
6+
7+.. sidebar:: build environment
8+
9+ Before looking deeper at the targets, first read about :ref:`makefile setup`
10+ and :ref:`make pyenv`.
11+
12+With the aim to simplify development cycles, started with :pull:`1756` a
13+``Makefile`` based boilerplate was added.
14+
15+The usage is simple, just type ``make {target-name}`` to *build* a target.
16+Calling the ``help`` target gives a first overview::
17+
18+ $ make help
19+ test - run developer tests
20+ docs - build documentation
21+ docs-live - autobuild HTML documentation while editing
22+ run - run developer instance
23+ install - developer install (./local)
24+ uninstall - uninstall (./local)
25+ gh-pages - build docs & deploy on gh-pages branch
26+ clean - drop builds and environments
27+ ...
28+
29+.. contents:: Contents
30+ :depth: 2
31+ :local:
32+ :backlinks: entry
33+
34+
35+.. _makefile setup:
36+
37+Setup
38+=====
39+
40+.. _git stash: https://git-scm.com/docs/git-stash
41+
42+The main setup is done in the :origin:`Makefile`::
43+
44+ export GIT_URL=https://github.com/asciimoo/searx
45+ export SEARX_URL=https://searx.me
46+ export DOCS_URL=https://asciimoo.github.io/searx
47+
48+.. sidebar:: fork & upstream
49+
50+ Commit changes in your (local) branch, fork or whatever, but do not push them
51+ upstream / `git stash`_ is your friend.
52+
53+:GIT_URL: Changes this, to point to your searx fork.
54+
55+:SEARX_URL: Changes this, to point to your searx instance.
56+
57+:DOCS_URL: If you host your own (branded) documentation, change this URL.
58+
59+.. _make pyenv:
60+
61+Python environment
62+==================
63+
64+.. sidebar:: activate environment
65+
66+ ``source ./local/py3/bin/activate``
67+
68+With Makefile we do no longer need to build up the virualenv manually (as
69+described in the :ref:`devquickstart` guide). Jump into your git working tree
70+and release a ``make pyenv``:
71+
72+.. code:: sh
73+
74+ $ cd ~/searx-clone
75+ $ make pyenv
76+ PYENV usage: source ./local/py3/bin/activate
77+ ...
78+
79+With target ``pyenv`` a development environment (aka virtualenv) was build up in
80+``./local/py3/``. To make a *developer install** of searx (:origin:`setup.py`)
81+into this environment make target ``install``
82+
83+.. code:: sh
84+
85+ $ make install
86+ PYENV usage: source ./local/py3/bin/activate
87+ PYENV using virtualenv from ./local/py3
88+ PYENV install .
89+
90+You have never to think about intermediate targets like ``pyenv`` or
91+``install``, the ``Makefile`` chains them as requisites. Just run your main
92+target.
93+
94+.. sidebar:: drop environment
95+
96+ To get rid of the existing environment before re-build use :ref:`clean target
97+ <make clean>` first.
98+
99+If you think, something goes wrong with your ./local environment or you change
100+the :origin:`setup.py` file (or the requirements listed in
101+:origin:`requirements-dev.txt` and :origin:`requirements.txt`), you have to call
102+:ref:`make clean`.
103+
104+
105+.. _make run:
106+
107+``make run``
108+============
109+
110+To get up a running a developer instance simply call ``make run``. This enables
111+*debug* option in :origin:`searx/settings.yml`, starts ``./searx/webapp.py``
112+instance, disables *debug* option and opens the site (xdg-open):
113+
114+.. code:: sh
115+
116+ $ make run
117+ PYENV usage: source ./local/py3/bin/activate
118+ PYENV install .
119+ ./local/py3/bin/python ./searx/webapp.py
120+ ...
121+ INFO:werkzeug: * Running on http://127.0.0.1:8888/ (Press CTRL+C to quit)
122+ ...
123+
124+.. _make clean:
125+
126+``make clean``
127+==============
128+
129+Drop all intermediate files, all builds, but keep sources untouched. Includes
130+target ``pyclean`` which drops ./local environment. Before calling ``make
131+clean`` stop all processes using :ref:`make pyenv`.
132+
133+.. code:: sh
134+
135+ $ make clean
136+ CLEAN pyclean
137+ CLEAN clean
138+
139+.. _make docs:
140+
141+``make docs docs-live docs-clean``
142+==================================
143+
144+We describe the usage of the ``doc*`` targets in the :ref:`How to contribute /
145+Documentation <contrib docs>` section. If you want to edit the documentation
146+read our :ref:`make docs-live` section. If you are working in your own brand,
147+adjust your :ref:`Makefile setup <makefile setup>`.
148+
149+
150+.. _make gh-pages:
151+
152+``make gh-pages``
153+=================
154+
155+To deploy on github.io first adjust your :ref:`Makefile setup <makefile
156+setup>`. For any further read :ref:`deploy on github.io`.
157+
158+.. _make test:
159+
160+``make test``
161+=============
162+
163+Runs a series of tests: ``test.pep8``, ``test.unit``, ``test.robot`` and does
164+additional :ref:`pylint checks <make pylint>`. You can run tests selective,
165+e.g.:
166+
167+.. code:: sh
168+
169+ $ make test.pep8 test.unit
170+ . ./local/py3/bin/activate; ./manage.sh pep8_check
171+ [!] Running pep8 check
172+ . ./local/py3/bin/activate; ./manage.sh unit_tests
173+ [!] Running unit tests
174+
175+.. _make pylint:
176+
177+``make pylint``
178+===============
179+
180+.. _Pylint: https://www.pylint.org/
181+
182+Before commiting its recommend to do some (more) linting. Pylint_ is known as
183+one of the best source-code, bug and quality checker for the Python programming
184+language. Pylint_ is not yet a quality gate within our searx project (like
185+:ref:`test.pep8 <make test>` it is), but Pylint_ can help to improve code
186+quality anyway. The pylint profile we use at searx project is found in
187+project's root folder :origin:`.pylintrc`.
188+
189+Code quality is a ongoing process. Don't try to fix all messages from Pylint,
190+run Pylint and check if your changed lines are bringing up new messages. If so,
191+fix it. By this, code quality gets incremental better and if there comes the
192+day, the linting is balanced out, we might decide to add Pylint as a quality
193+gate.
194+
195+
196+``make pybuild``
197+================
198+
199+.. _PyPi: https://pypi.org/
200+.. _twine: https://twine.readthedocs.io/en/latest/
201+
202+Build Python packages in ``./dist/py``.
203+
204+.. code:: sh
205+
206+ $ make pybuild
207+ ...
208+ BUILD pybuild
209+ running sdist
210+ running egg_info
211+ ...
212+ $ ls ./dist/py/
213+ searx-0.15.0-py3-none-any.whl searx-0.15.0.tar.gz
214+
215+To upload packages to PyPi_, there is also a ``upload-pypi`` target. It needs
216+twine_ to be installed. Since you are not the owner of :pypi:`searx` you will
217+never need the latter.