mirror of
https://github.com/searxng/searxng.git
synced 2025-07-12 15:59:21 +02:00
[doc] improve documentation of make targets and ./manage script
BTW force modularization of the ./mange script into sub modules: - utils/lib_sxng_data.sh - utils/lib_sxng_node.sh - utils/lib_sxng_static.sh - utils/lib_sxng_test.sh - utils/lib_sxng_themes.sh Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser
Markus Heiser
parent
1d0abb7157
commit
64100db904
16 changed files with 767 additions and 654 deletions
|
|
@ -148,7 +148,7 @@ live build
|
|||
Live build is like WYSIWYG. If you want to edit the documentation, its
|
||||
recommended to use. The Makefile target ``docs.live`` builds the docs, opens
|
||||
URL in your favorite browser and rebuilds every time a reST file has been
|
||||
changed.
|
||||
changed (:ref:`make docs.clean`).
|
||||
|
||||
.. code:: sh
|
||||
|
||||
|
|
@ -183,3 +183,8 @@ commit and push:
|
|||
.. code:: sh
|
||||
|
||||
$ make docs.clean docs.gh-pages
|
||||
|
||||
.. attention::
|
||||
|
||||
If you are working in your own brand, don't forgett to adjust your
|
||||
:ref:`settings brand`.
|
||||
|
|
|
|||
|
|
@ -1,32 +1,49 @@
|
|||
.. _makefile:
|
||||
|
||||
========
|
||||
Makefile
|
||||
========
|
||||
=======================
|
||||
Makefile & ``./manage``
|
||||
=======================
|
||||
|
||||
.. _gnu-make: https://www.gnu.org/software/make/manual/make.html#Introduction
|
||||
|
||||
All relevant build and development tasks are implemented in the
|
||||
:origin:`./manage <manage>` script and for CI or IDE integration a small
|
||||
:origin:`Makefile` wrapper is available. If you are not familiar with
|
||||
Makefiles, we recommend to read gnu-make_ introduction.
|
||||
|
||||
.. sidebar:: build environment
|
||||
|
||||
Before looking deeper at the targets, first read about :ref:`make
|
||||
install`.
|
||||
|
||||
To install system requirements follow :ref:`buildhosts`.
|
||||
To install developer requirements follow :ref:`buildhosts`.
|
||||
|
||||
All relevant build tasks are implemented in :origin:`manage` and for CI or
|
||||
IDE integration a small ``Makefile`` wrapper is available. If you are not
|
||||
familiar with Makefiles, we recommend to read gnu-make_ introduction.
|
||||
|
||||
The usage is simple, just type ``make {target-name}`` to *build* a target.
|
||||
Calling the ``help`` target gives a first overview (``make help``):
|
||||
|
||||
.. program-output:: bash -c "cd ..; make --no-print-directory help"
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:local:
|
||||
:backlinks: entry
|
||||
|
||||
The usage is simple, just type ``make {target-name}`` to *build* a target.
|
||||
Calling the ``help`` target gives a first overview (``make help``):
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: ``make``
|
||||
|
||||
.. program-output:: bash -c "cd ..; make --no-print-directory help"
|
||||
|
||||
|
||||
.. group-tab:: ``./manage``
|
||||
|
||||
The Makefile targets are implemented for comfort, if you can do without
|
||||
tab-completion and need to have a more granular control, use
|
||||
:origin:`manage` without the Makefile wrappers.
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ ./manage help
|
||||
|
||||
.. _make install:
|
||||
|
||||
Python environment (``make install``)
|
||||
|
|
@ -158,29 +175,49 @@ Node.js environment (``make node.env``)
|
|||
Manager) to install latest LTS of Node.js_ locally: there is no need to
|
||||
install nvm_ or npm_ on your system.
|
||||
|
||||
Use ``make nvm.status`` to get the current status of you Node.js_ and nvm_ setup.
|
||||
To install NVM_ and Node.js_ in once you can use :ref:`make nvm.nodejs`.
|
||||
|
||||
Here is the output you will typically get on a Ubuntu 20.04 system which serves
|
||||
only a `no longer active <https://nodejs.org/en/about/releases/>`_ Release
|
||||
`Node.js v10.19.0 <https://packages.ubuntu.com/focal/nodejs>`_.
|
||||
.. _make nvm:
|
||||
|
||||
::
|
||||
NVM ``make nvm.install nvm.status``
|
||||
-----------------------------------
|
||||
|
||||
$ make nvm.status
|
||||
INFO: Node.js is installed at /usr/bin/node
|
||||
INFO: Node.js is version v10.19.0
|
||||
WARN: minimal Node.js version is 16.13.0
|
||||
INFO: npm is installed at /usr/bin/npm
|
||||
INFO: npm is version 6.14.4
|
||||
WARN: NVM is not installed
|
||||
INFO: to install NVM and Node.js (LTS) use: manage nvm install --lts
|
||||
Use ``make nvm.status`` to get the current status of your Node.js_ and nvm_
|
||||
setup.
|
||||
|
||||
To install you can also use :ref:`make nvm.nodejs`
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: nvm.install
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ LANG=C make nvm.install
|
||||
INFO: install (update) NVM at ./searxng/.nvm
|
||||
INFO: clone: https://github.com/nvm-sh/nvm.git
|
||||
|| Cloning into './searxng/.nvm'...
|
||||
INFO: checkout v0.39.4
|
||||
|| HEAD is now at 8fbf8ab v0.39.4
|
||||
|
||||
.. group-tab:: nvm.status (ubu2004)
|
||||
|
||||
Here is the output you will typically get on a Ubuntu 20.04 system which
|
||||
serves only a `no longer active <https://nodejs.org/en/about/releases/>`_
|
||||
Release `Node.js v10.19.0 <https://packages.ubuntu.com/focal/nodejs>`_.
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ make nvm.status
|
||||
INFO: Node.js is installed at /usr/bin/node
|
||||
INFO: Node.js is version v10.19.0
|
||||
WARN: minimal Node.js version is 16.13.0
|
||||
INFO: npm is installed at /usr/bin/npm
|
||||
INFO: npm is version 6.14.4
|
||||
WARN: NVM is not installed
|
||||
|
||||
.. _make nvm.nodejs:
|
||||
|
||||
``make nvm.nodejs``
|
||||
===================
|
||||
-------------------
|
||||
|
||||
Install latest Node.js_ LTS locally (uses nvm_)::
|
||||
|
||||
|
|
@ -213,10 +250,29 @@ sources of the theme need to be rebuild. You can do that by running::
|
|||
$ make themes.all
|
||||
|
||||
Alternatively to ``themes.all`` you can run *live builds* of the theme you are
|
||||
modify::
|
||||
modify (:ref:`make themes`)::
|
||||
|
||||
$ LIVE_THEME=simple make run
|
||||
|
||||
.. _make format.python:
|
||||
|
||||
``make format.python``
|
||||
======================
|
||||
|
||||
Format Python sourcee code using `Black code style`_. See ``$BLACK_OPTIONS``
|
||||
and ``$BLACK_TARGETS`` in :origin:`Makefile`.
|
||||
|
||||
.. attention::
|
||||
|
||||
We stuck at Black 22.12.0, please read comment in PR `Bump black from 22.12.0
|
||||
to 23.1.0`_
|
||||
|
||||
.. _Bump black from 22.12.0 to 23.1.0:
|
||||
https://github.com/searxng/searxng/pull/2159#pullrequestreview-1284094735
|
||||
|
||||
.. _Black code style:
|
||||
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html
|
||||
|
||||
.. _make clean:
|
||||
|
||||
``make clean``
|
||||
|
|
@ -237,18 +293,34 @@ calling ``make clean`` stop all processes using the :ref:`make install` or
|
|||
|
||||
.. _make docs:
|
||||
|
||||
``make docs docs.autobuild docs.clean``
|
||||
=======================================
|
||||
``make docs``
|
||||
=============
|
||||
|
||||
Target ``docs`` builds the documentation:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ make docs
|
||||
HTML ./docs --> file://
|
||||
DOCS build build/docs/includes
|
||||
...
|
||||
The HTML pages are in dist/docs.
|
||||
|
||||
.. _make docs.clean:
|
||||
|
||||
``make docs.clean docs.live``
|
||||
----------------------------------
|
||||
|
||||
We describe the usage of the ``doc.*`` targets in the :ref:`How to contribute /
|
||||
Documentation <contrib docs>` section. If you want to edit the documentation
|
||||
read our :ref:`make docs.live` section. If you are working in your own brand,
|
||||
adjust your :ref:`settings brand`.
|
||||
|
||||
|
||||
.. _make docs.gh-pages:
|
||||
|
||||
``make docs.gh-pages``
|
||||
======================
|
||||
----------------------
|
||||
|
||||
To deploy on github.io first adjust your :ref:`settings brand`. For any
|
||||
further read :ref:`deploy on github.io`.
|
||||
|
|
@ -261,17 +333,17 @@ further read :ref:`deploy on github.io`.
|
|||
Runs a series of tests: :ref:`make test.pylint`, ``test.pep8``, ``test.unit``
|
||||
and ``test.robot``. You can run tests selective, e.g.::
|
||||
|
||||
$ make test.pep8 test.unit test.sh
|
||||
$ make test.pep8 test.unit test.shell
|
||||
TEST test.pep8 OK
|
||||
...
|
||||
TEST test.unit OK
|
||||
...
|
||||
TEST test.sh OK
|
||||
TEST test.shell OK
|
||||
|
||||
.. _make test.shell:
|
||||
|
||||
``make test.shell``
|
||||
===================
|
||||
-------------------
|
||||
|
||||
:ref:`sh lint` / if you have changed some bash scripting run this test before
|
||||
commit.
|
||||
|
|
@ -279,7 +351,7 @@ commit.
|
|||
.. _make test.pylint:
|
||||
|
||||
``make test.pylint``
|
||||
====================
|
||||
--------------------
|
||||
|
||||
.. _Pylint: https://www.pylint.org/
|
||||
|
||||
|
|
@ -289,8 +361,8 @@ found in project's root folder :origin:`.pylintrc`.
|
|||
|
||||
.. _make search.checker:
|
||||
|
||||
``search.checker.{engine name}``
|
||||
================================
|
||||
``make search.checker.{engine name}``
|
||||
=====================================
|
||||
|
||||
To check all engines::
|
||||
|
||||
|
|
@ -318,3 +390,63 @@ To filter out HTTP redirects (3xx_)::
|
|||
https://news.google.com:443 "GET /search?q=computer&hl=en&lr=lang_en&ie=utf8&oe=utf8&ceid=US%3Aen&gl=US HTTP/1.1" 302 0
|
||||
https://news.google.com:443 "GET /search?q=computer&hl=en-US&lr=lang_en&ie=utf8&oe=utf8&ceid=US:en&gl=US HTTP/1.1" 200 None
|
||||
--
|
||||
|
||||
.. _make themes:
|
||||
|
||||
``make themes.*``
|
||||
=================
|
||||
|
||||
.. sidebar:: further read
|
||||
|
||||
- :ref:`devquickstart`
|
||||
|
||||
The :origin:`Makefile` targets ``make theme.*`` cover common tasks to build the
|
||||
theme(s). The ``./manage themes.*`` command line can be used to convenient run
|
||||
common theme build tasks.
|
||||
|
||||
.. program-output:: bash -c "cd ..; ./manage themes.help"
|
||||
|
||||
To get live builds while modifying CSS & JS use (:ref:`make run`):
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ LIVE_THEME=simple make run
|
||||
|
||||
.. _make static.build:
|
||||
|
||||
``make static.build.*``
|
||||
=======================
|
||||
|
||||
.. sidebar:: further read
|
||||
|
||||
- :ref:`devquickstart`
|
||||
|
||||
The :origin:`Makefile` targets ``static.build.*`` cover common tasks to build (a
|
||||
commit of) the static files. The ``./manage static.build..*`` command line
|
||||
can be used to convenient run common build tasks of the satic files.
|
||||
|
||||
.. program-output:: bash -c "cd ..; ./manage static.help"
|
||||
|
||||
|
||||
.. _manage redis.help:
|
||||
|
||||
``./manage redis.help``
|
||||
=======================
|
||||
|
||||
The ``./manage redis.*`` command line can be used to convenient run common Redis
|
||||
tasks (:ref:`Redis developer notes`).
|
||||
|
||||
.. program-output:: bash -c "cd ..; ./manage redis.help"
|
||||
|
||||
|
||||
.. _manage go.help:
|
||||
|
||||
``./manage go.help``
|
||||
====================
|
||||
|
||||
The ``./manage go.*`` command line can be used to convenient run common `go
|
||||
(wiki)`_ tasks.
|
||||
|
||||
.. _go (wiki): https://en.wikipedia.org/wiki/Go_(programming_language)
|
||||
|
||||
.. program-output:: bash -c "cd ..; ./manage go.help"
|
||||
|
|
|
|||
|
|
@ -7,8 +7,16 @@ Development Quickstart
|
|||
.. _npm: https://www.npmjs.com/
|
||||
.. _Node.js: https://nodejs.org/
|
||||
|
||||
SearXNG loves developers, just clone and start hacking. All the rest is done for
|
||||
you simply by using :ref:`make <makefile>`.
|
||||
|
||||
.. sidebar:: further read
|
||||
|
||||
- :ref:`makefile`
|
||||
- :ref:`buildhosts`
|
||||
|
||||
SearXNG loves developers; Developers do not need to worry about tool chains, the
|
||||
usual developer tasks can be comfortably executed via :ref:`make <makefile>`.
|
||||
|
||||
Don't hesitate, just clone SearXNG's sources and start hacking right now ..
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
|
@ -18,25 +26,23 @@ Here is how a minimal workflow looks like:
|
|||
|
||||
1. *start* hacking
|
||||
2. *run* your code: :ref:`make run`
|
||||
3. *test* your code: :ref:`make test`
|
||||
3. *format & test* your code: :ref:`make format.python` and :ref:`make test`
|
||||
|
||||
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.
|
||||
|
||||
If you implement themes, you will need to setup a :ref:`make node.env` once:
|
||||
.. sidebar:: further read
|
||||
|
||||
.. code:: bash
|
||||
- :ref:`make nvm`
|
||||
- :ref:`make themes`
|
||||
|
||||
make node.env
|
||||
If you implement themes, you will need to setup a :ref:`Node.js environment
|
||||
<make node.env>`: ``make node.env``
|
||||
|
||||
Before you call *make run* (2.), you need to compile the modified styles and
|
||||
JavaScript:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
make themes.all
|
||||
JavaScript: ``make themes.all``
|
||||
|
||||
Alternatively you can also compile selective the theme you have modified,
|
||||
e.g. the *simple* theme.
|
||||
|
|
@ -49,6 +55,10 @@ e.g. the *simple* theme.
|
|||
|
||||
To get live builds while modifying CSS & JS use: ``LIVE_THEME=simple make run``
|
||||
|
||||
.. sidebar:: further read
|
||||
|
||||
- :ref:`make static.build`
|
||||
|
||||
If you finished your *tests* you can start to commit your changes. To separate
|
||||
the modified source code from the build products first run:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue