doc: add reST templating // incl. generic engine tabe

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/admin/engines.rst

@@ -0,0 +1,68 @@
+.. _engines generic:
+
+=======
+engines
+=======
+
+.. sidebar:: Further reading ..
+
+   - :ref:`engines generic`
+   - :ref:`configured engines`
+   - :ref:`engine settings`
+   - :ref:`engine file`
+
+============= =========== ==================== ============
+:ref:`engine settings`    :ref:`engine file`
+------------------------- ---------------------------------
+Name (cfg)                Categories
+------------------------- ---------------------------------
+Engine        ..          Paging support       **P**
+------------------------- -------------------- ------------
+Shortcut      **S**       Language support     **L**
+Timeout       **TO**      Time range support   **TR**
+Disabled      **D**       Offline              **O**
+------------- ----------- -------------------- ------------
+Suspend end   **SE**
+------------- ----------- ---------------------------------
+Safe search   **SS**
+============= =========== =================================
+
+Configuration defaults (at built time):
+
+.. _configured engines:
+
+.. jinja:: webapp
+
+   .. flat-table:: Engines configured at built time (defaults)
+      :header-rows: 1
+      :stub-columns: 2
+
+      * - Name (cfg)
+        - S
+        - Engine
+        - TO
+        - Categories
+        - P
+        - L
+        - SS
+        - D
+        - TR
+        - O
+        - SE
+
+      {% for name, mod in engines.items() %}
+
+      * - {{name}}
+        - !{{mod.shortcut}}
+        - {{mod.__name__}}
+        - {{mod.timeout}}
+        - {{", ".join(mod.categories)}}
+        - {{(mod.paging and "y") or ""}}
+        - {{(mod.language_support and "y") or ""}}
+        - {{(mod.safesearch and "y") or ""}}
+        - {{(mod.disabled and "y") or ""}}
+        - {{(mod.time_range_support and "y") or ""}}
+        - {{(mod.offline and "y") or ""}}
+        - {{mod.suspend_end_time}}
+
+     {% endfor %}

docs/admin/index.rst

@@ -9,3 +9,4 @@ Administrator documentation
    api
    filtron
    morty
+   engines

docs/conf.py

@@ -22,6 +22,11 @@ master_doc = "index"
 source_suffix = '.rst'
 numfig = True
 
+from searx import webapp
+jinja_contexts = {
+    'webapp': dict(**webapp.__dict__)
+}
+
 # usage::   lorem :patch:`f373169` ipsum
 extlinks = {}
 
@@ -52,11 +57,8 @@ extensions = [
     "sphinx.ext.intersphinx",
     "pallets_sphinx_themes",
     "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst
+    "sphinxcontrib.jinja",  # https://github.com/tardyp/sphinx-jinja
     'linuxdoc.rstFlatTable',    # Implementation of the 'flat-table' reST-directive.
-    'linuxdoc.rstKernelDoc',    # Implementation of the 'kernel-doc' reST-directive.
-    'linuxdoc.kernel_include',  # Implementation of the 'kernel-include' reST-directive.
-    'linuxdoc.manKernelDoc',    # Implementation of the 'kernel-doc-man' builder
-    'linuxdoc.cdomain',         # Replacement for the sphinx c-domain.
     'linuxdoc.kfigure',         # Sphinx extension which implements scalable image handling.
 ]
 

docs/dev/engine_overview.rst

@@ -29,6 +29,7 @@ the ones in the engine file.
 It does not matter if an option is stored in the engine file or in the
 settings.  However, the standard way is the following:
 
+.. _engine file:
 
 engine file
 -----------
@@ -43,6 +44,7 @@ time_range_support      boolean     support search time range
 offline                 boolean     engine runs offline
 ======================= =========== ===========================================
 
+.. _engine settings:
 
 settings.yml
 ------------

docs/dev/reST.rst

@@ -26,6 +26,7 @@ The sources of Searx's documentation are located at :origin:`docs`.  Run
    - `sphinx cross references`_
    - linuxdoc_
    - intersphinx_
+   - sphinx-jinja_
    - `Sphinx's autodoc`_
    - `Sphinx's Python domain`_, `Sphinx's C domain`_
    - SVG_, ImageMagick_
@@ -1079,6 +1080,36 @@ Content of file ``csv_table.txt``:
       :stub-columns: 1
       :file: csv_table.txt
 
+Templating
+==========
+
+.. sidebar:: Build environment
+
+   All *generic-doc* tasks are running in the :ref:`build environment <make
+   pyenv>`.
+
+Templating is suitable for documentation which is created generic at the build
+time.  The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
+environment <make pyenv>` with installed searx modules.  We use this e.g. to
+build chapter: :ref:`engines generic`.
+
+Here is the content of the :origin:`docs/admin/engines.rst`:
+
+.. literalinclude:: ../admin/engines.rst
+   :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``.
+
+.. code:: py
+
+   from searx import webapp
+   jinja_contexts = {
+       'webapp': dict(**webapp.__dict__)
+   }
+
 
 
 .. _KISS: https://en.wikipedia.org/wiki/KISS_principle
@@ -1109,7 +1140,8 @@ Content of file ``csv_table.txt``:
 .. _docutils: http://docutils.sourceforge.net/docs/index.html
 .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
 .. _linuxdoc: https://return42.github.io/linuxdoc
-
+.. _jinja: https://jinja.palletsprojects.com/
+.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
 .. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
 .. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
 .. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf

docs/dev/search_api.rst

@@ -14,6 +14,13 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying.
 Parameters
 ==========
 
+.. sidebar:: Further reading ..
+
+   - :ref:`engines generic`
+   - :ref:`configured engines`
+   - :ref:`engine settings`
+   - :ref:`engine file`
+
 ``q`` : required
   The search query.  This string is passed to external search services.  Thus,
   searx supports syntax of each search service.  For example, ``site:github.com

requirements-dev.txt

@@ -12,3 +12,4 @@ unittest2==1.1.0
 zope.testrunner==4.5.1
 selenium==3.141.0
 linuxdoc @ git+http://github.com/return42/linuxdoc.git
+sphinx-jinja