mirror of
https://github.com/searxng/searxng.git
synced 2024-11-13 08:10:12 +01:00
doc: add reST templating // incl. generic engine tabe
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
parent
c2b9aa0c2f
commit
d1154202bc
68
docs/admin/engines.rst
Normal file
68
docs/admin/engines.rst
Normal file
@ -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 %}
|
@ -9,3 +9,4 @@ Administrator documentation
|
||||
api
|
||||
filtron
|
||||
morty
|
||||
engines
|
||||
|
10
docs/conf.py
10
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.
|
||||
]
|
||||
|
||||
|
@ -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
|
||||
------------
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user