2 files changed, 43 insertions, 5 deletions
diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst
index 699729a28..c43855617 100644
--- a/docs/dev/makefile.rst
+++ b/docs/dev/makefile.rst
@@ -150,6 +150,35 @@ 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:`Makefile setup <makefile setup>`.
 
+.. _make books:
+
+``make books/{name}.html books/{name}.pdf``
+===========================================
+
+.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
+.. _XeTeX: https://tug.org/xetex/
+
+.. sidebar:: info
+
+   To build PDF a XeTeX_ is needed, see :ref:`buildhosts`.
+
+
+The ``books/{name}.*`` targets are building *books*.  A *book* is a
+sub-directory containing a ``conf.py`` file.  One example is the user handbook
+which can deployed separately (:origin:`docs/user/conf.py`).  Such ``conf.py``
+do inherit from :origin:`docs/conf.py` and overwrite values to fit *book's*
+needs.
+
+With the help of Intersphinx_ (:ref:`reST smart ref`) the links to searx’s
+documentation outside of the book will be bound by the object inventory of
+``DOCS_URL``.  Take into account that URLs will be picked from the inventary at
+documentation's build time.
+
+Use ``make docs-help`` to see which books available:
+
+.. program-output:: bash -c "cd ..; make --no-print-directory docs-help"
+   :ellipsis: 0,-6
+
 
 .. _make gh-pages:
 
diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst
index 963378748..39cd9f671 100644
--- a/docs/dev/reST.rst
+++ b/docs/dev/reST.rst
@@ -319,6 +319,9 @@ To list all anchors of the inventory (e.g. ``python``) use:
 .. code:: sh
 
    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+   ...
+   $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
+   ...
 
 Literal blocks
 ==============
@@ -1286,15 +1289,21 @@ build chapter: :ref:`engines generic`.  Below the jinja directive from the
    :language: reST
    :start-after: .. _configured engines:
 
-The context for the template is selected in the line ``.. jinja:: webapp``.  In
-sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
-points to the name space of the python module: ``webapp``.
+The context for the template is selected in the line ``.. jinja:: searx``.  In
+sphinx's build configuration (:origin:`docs/conf.py`) the ``searx`` context
+contains the ``engines`` and ``plugins``.
 
 .. code:: py
 
-   from searx import webapp
+   import searx.search
+   import searx.engines
+   import searx.plugins
+   searx.search.initialize()
    jinja_contexts = {
-       'webapp': dict(**webapp.__dict__)
+      'searx': {
+         'engines': searx.engines.engines,
+         'plugins': searx.plugins.plugins
+      },
    }