searxngRebrandZaclys/docs/admin/buildhosts.rst
Markus Heiser 5720844fcd [doc] rearranges Settings & Engines docs for better readability
We have built up detailed documentation of the *settings* and the *engines* over
the past few years.  However, this documentation was still spread over various
chapters and was difficult to navigate in its entirety.

This patch rearranges the Settings & Engines documentation for better
readability.

To review new ordered docs::

   make docs.clean docs.live

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
2023-07-01 22:45:19 +02:00

3.6 KiB

Buildhosts

This article needs some work

If you have any contribution send us your PR <../pulls>, see how to contribute.

To get best results from build, it's recommend to install additional packages on build hosts (see searxng.sh).:

sudo -H ./utils/searxng.sh install buildhost

This will install packages needed by searx:

$DOCS_BUILD/includes/searxng.rst

and packages needed to build docuemtation and run tests:

$DOCS_BUILD/includes/searxng.rst

Build docs

Sphinx build needs

Most of the sphinx requirements are installed from setup.py and the docs can be build from scratch with make docs.html. For better math and image processing additional packages are needed. The XeTeX needed not only for PDF creation, it's also needed for math when HTML output is build.

To be able to do sphinx:math-support without CDNs, the math are rendered as images (sphinx.ext.imgmath extension).

Here is the extract from the docs/conf.py file, setting math renderer to imgmath:

../conf.py

If your docs build (make docs.html) shows warnings like this:

WARNING: dot(1) not found, for better output quality install \
         graphviz from https://www.graphviz.org
..
WARNING: LaTeX command 'latex' cannot be run (needed for math \
         display), check the imgmath_latex setting

you need to install additional packages on your build host, to get better HTML output.

Ubuntu / debian

$ sudo apt install graphviz imagemagick texlive-xetex librsvg2-bin

Arch Linux

$ sudo pacman -S graphviz imagemagick texlive-bin extra/librsvg

Fedora / RHEL

$ sudo dnf install graphviz graphviz-gd texlive-xetex-bin librsvg2-tools

For PDF output you also need:

Ubuntu / debian

$ sudo apt texlive-latex-recommended texlive-extra-utils ttf-dejavu

Arch Linux

$ sudo pacman -S texlive-core texlive-latexextra ttf-dejavu

Fedora / RHEL

$ sudo dnf install \
   texlive-collection-fontsrecommended texlive-collection-latex \
dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts \
ImageMagick

Lint shell scripts

To lint shell scripts, we use ShellCheck - a shell script static analysis tool.

Ubuntu / debian

$ sudo apt install shellcheck

Arch Linux

$ sudo pacman -S shellcheck

Fedora / RHEL

$ sudo dnf install ShellCheck