doc: add reST primer (inital / WIP)

preview: https://return42.github.io/searx/dev/reST.html

includes:

- :class: rst-example // admonitions with (rendered) reST markup example
- extlinks to docutils
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/_themes/searx/static/searx.css

@@ -28,3 +28,45 @@ p.sidebar-title, .sidebar p {
   list-style-type: disclosure-closed;
 }
 
+
+/* admonitions with (rendered) reST markup examples (:class: rst-example)
+ *
+ * .. admonition:: title of the example
+ *     :class: rst-example
+ *     ....
+/* navigation menu: use sans font and select light/dark colors for better
+* contrast.
+*/
+
+div.rst-example {
+    padding-left: 12px;
+    padding-right: 12px;
+    background-color: white;
+    transform: scale(0.9);
+    transition: transform 1s;
+}
+
+/* div.rst-example > .admonition-title { */
+/*     background-color: inherit; */
+/*     color: inherit; */
+/* } */
+
+/* div.rst-example > .admonition-title:after{ */
+/*     font-family: inherit; */
+/*     font-style: italic; */
+/*     content: "     // hover mouse over .."; */
+/* } */
+
+@media screen {
+   div.rst-example:hover {
+       transform: scale(1);
+       background-color: inherit;
+       padding-left: inherit;
+       padding-right: inherit;
+       border-left: inherit;
+   }
+
+   div.rst-example:hover > .admonition-title {
+       display: none;
+   }
+}

docs/conf.py

@@ -14,6 +14,7 @@ project = u'searx'
 copyright = u'2015-2019, Adam Tauber, Noémi Ványi'
 author = u'Adam Tauber'
 release, version = VERSION_STRING, VERSION_STRING
+highlight_language = 'none'
 
 # General --------------------------------------------------------------
 
@@ -34,6 +35,12 @@ extlinks['search'] = (SEARX_URL + '/%s', '#')
 extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
 extlinks['pypi'] = ('https://pypi.org/project/%s', 'PyPi: ')
 extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '')
+extlinks['duref'] = (
+    'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '')
+extlinks['durole'] = (
+    'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '')
+extlinks['dudir'] =  (
+    'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '')
 
 extensions = [
     'sphinx.ext.extlinks',
@@ -46,9 +53,9 @@ extensions = [
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    # "flask": ("https://flask.palletsprojects.com/", None),
+    "flask": ("https://flask.palletsprojects.com/", None),
     # "werkzeug": ("https://werkzeug.palletsprojects.com/", None),
-    # "jinja": ("https://jinja.palletsprojects.com/", None),
+    "jinja": ("https://jinja.palletsprojects.com/", None),
 }
 
 issues_github_path = "asciimoo/searx"

docs/dev/index.rst

@@ -12,3 +12,4 @@ Developer documentation
    plugins
    translation
    makefile
+   reST

docs/dev/makefile.rst

@@ -81,7 +81,7 @@ and release a ``make pyenv``:
 
 With target ``pyenv`` a development environment (aka virtualenv) was build up in
 ``./local/py3/``.  To make a *developer install* of searx (:origin:`setup.py`)
-into this environment make target ``install``
+into this environment, use make target ``install``:
 
 .. code:: sh