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

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-21 17:13:38 +01:00
parent c2b9aa0c2f
commit d1154202bc
7 changed files with 118 additions and 5 deletions

68
docs/admin/engines.rst Normal file
View 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 %}

View file

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

View file

@ -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.
]

View file

@ -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
------------

View file

@ -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

View file

@ -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

View file

@ -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