git.iko.soy/searx
on master help sign in
doc: add reST templating // incl. generic engine tabe

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

commitd1154202bcd27a7cf3a1bed524ee6b24955df8af authorMarkus Heiser <markus.heiser@darmarit.de> dateSat 21 Dec 2019, 17:13 (7 years ago) parentc2b9aa0
7 files changed+118−5
compare with master
unifiedsplit
docs/admin/engines.rst+68 docs/admin/index.rst+1 docs/conf.py+6−4 docs/dev/engine_overview.rst+2 docs/dev/reST.rst+33−1 docs/dev/search_api.rst+7 requirements-dev.txt+1
docs/admin/engines.rstnew file+68
@@ -0,0 +1,68 @@
1+.. _engines generic:
2+
3+=======
4+engines
5+=======
6+
7+.. sidebar:: Further reading ..
8+
9+ - :ref:`engines generic`
10+ - :ref:`configured engines`
11+ - :ref:`engine settings`
12+ - :ref:`engine file`
13+
14+============= =========== ==================== ============
15+:ref:`engine settings` :ref:`engine file`
16+------------------------- ---------------------------------
17+Name (cfg) Categories
18+------------------------- ---------------------------------
19+Engine .. Paging support **P**
20+------------------------- -------------------- ------------
21+Shortcut **S** Language support **L**
22+Timeout **TO** Time range support **TR**
23+Disabled **D** Offline **O**
24+------------- ----------- -------------------- ------------
25+Suspend end **SE**
26+------------- ----------- ---------------------------------
27+Safe search **SS**
28+============= =========== =================================
29+
30+Configuration defaults (at built time):
31+
32+.. _configured engines:
33+
34+.. jinja:: webapp
35+
36+ .. flat-table:: Engines configured at built time (defaults)
37+ :header-rows: 1
38+ :stub-columns: 2
39+
40+ * - Name (cfg)
41+ - S
42+ - Engine
43+ - TO
44+ - Categories
45+ - P
46+ - L
47+ - SS
48+ - D
49+ - TR
50+ - O
51+ - SE
52+
53+ {% for name, mod in engines.items() %}
54+
55+ * - {{name}}
56+ - !{{mod.shortcut}}
57+ - {{mod.__name__}}
58+ - {{mod.timeout}}
59+ - {{", ".join(mod.categories)}}
60+ - {{(mod.paging and "y") or ""}}
61+ - {{(mod.language_support and "y") or ""}}
62+ - {{(mod.safesearch and "y") or ""}}
63+ - {{(mod.disabled and "y") or ""}}
64+ - {{(mod.time_range_support and "y") or ""}}
65+ - {{(mod.offline and "y") or ""}}
66+ - {{mod.suspend_end_time}}
67+
68+ {% endfor %}
docs/admin/index.rst+1
@@ -9,3 +9,4 @@ Administrator documentation
99 api
1010 filtron
1111 morty
12+ engines
docs/conf.py+6−4
@@ -22,6 +22,11 @@ master_doc = "index"
2222source_suffix = '.rst'
2323numfig = True
2424
25+from searx import webapp
26+jinja_contexts = {
27+ 'webapp': dict(**webapp.__dict__)
28+}
29+
2530# usage:: lorem :patch:`f373169` ipsum
2631extlinks = {}
2732
@@ -52,11 +57,8 @@ extensions = [
5257 "sphinx.ext.intersphinx",
5358 "pallets_sphinx_themes",
5459 "sphinx_issues", # https://github.com/sloria/sphinx-issues/blob/master/README.rst
60+ "sphinxcontrib.jinja", # https://github.com/tardyp/sphinx-jinja
5561 'linuxdoc.rstFlatTable', # Implementation of the 'flat-table' reST-directive.
56− 'linuxdoc.rstKernelDoc', # Implementation of the 'kernel-doc' reST-directive.
57− 'linuxdoc.kernel_include', # Implementation of the 'kernel-include' reST-directive.
58− 'linuxdoc.manKernelDoc', # Implementation of the 'kernel-doc-man' builder
59− 'linuxdoc.cdomain', # Replacement for the sphinx c-domain.
6062 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling.
6163]
6264
docs/dev/engine_overview.rst+2
@@ -29,6 +29,7 @@ the ones in the engine file.
2929It does not matter if an option is stored in the engine file or in the
3030settings. However, the standard way is the following:
3131
32+.. _engine file:
3233
3334engine file
3435-----------
@@ -43,6 +44,7 @@ time_range_support boolean support search time range
4344offline boolean engine runs offline
4445======================= =========== ===========================================
4546
47+.. _engine settings:
4648
4749settings.yml
4850------------
docs/dev/reST.rst+33−1
@@ -26,6 +26,7 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
2626 - `sphinx cross references`_
2727 - linuxdoc_
2828 - intersphinx_
29+ - sphinx-jinja_
2930 - `Sphinx's autodoc`_
3031 - `Sphinx's Python domain`_, `Sphinx's C domain`_
3132 - SVG_, ImageMagick_
@@ -1079,6 +1080,36 @@ Content of file ``csv_table.txt``:
10791080 :stub-columns: 1
10801081 :file: csv_table.txt
10811082
1083+Templating
1084+==========
1085+
1086+.. sidebar:: Build environment
1087+
1088+ All *generic-doc* tasks are running in the :ref:`build environment <make
1089+ pyenv>`.
1090+
1091+Templating is suitable for documentation which is created generic at the build
1092+time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
1093+environment <make pyenv>` with installed searx modules. We use this e.g. to
1094+build chapter: :ref:`engines generic`.
1095+
1096+Here is the content of the :origin:`docs/admin/engines.rst`:
1097+
1098+.. literalinclude:: ../admin/engines.rst
1099+ :language: reST
1100+ :start-after: .. _configured engines:
1101+
1102+The context for the template is selected in the line ``.. jinja:: webapp``. In
1103+sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
1104+points to the name space of the python module: ``webapp``.
1105+
1106+.. code:: py
1107+
1108+ from searx import webapp
1109+ jinja_contexts = {
1110+ 'webapp': dict(**webapp.__dict__)
1111+ }
1112+
10821113
10831114
10841115.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
@@ -1109,7 +1140,8 @@ Content of file ``csv_table.txt``:
11091140.. _docutils: http://docutils.sourceforge.net/docs/index.html
11101141.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
11111142.. _linuxdoc: https://return42.github.io/linuxdoc
1112−
1143+.. _jinja: https://jinja.palletsprojects.com/
1144+.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
11131145.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
11141146.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
11151147.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
docs/dev/search_api.rst+7
@@ -14,6 +14,13 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying.
1414Parameters
1515==========
1616
17+.. sidebar:: Further reading ..
18+
19+ - :ref:`engines generic`
20+ - :ref:`configured engines`
21+ - :ref:`engine settings`
22+ - :ref:`engine file`
23+
1724``q`` : required
1825 The search query. This string is passed to external search services. Thus,
1926 searx supports syntax of each search service. For example, ``site:github.com
requirements-dev.txt+1
@@ -12,3 +12,4 @@ unittest2==1.1.0
1212zope.testrunner==4.5.1
1313selenium==3.141.0
1414linuxdoc @ git+http://github.com/return42/linuxdoc.git
15+sphinx-jinja