[mod] replace /help by /info pages and include pages in project docs

This patch implements a bolierplate to share content from info-pages of the
SearXNG instance (URL /info) with the project documentation (path /docs/user).

The info pages are using Markdown (CommonMark), to include them in the project
documentation (reST) the myst-parser [1] is used in the Sphinx-doc build chain.

If base_url is known (defined in settings.yml) links to the instance are also
inserted into the project documentation::

    searxng_extra/docs_prebuild

[1] https://www.sphinx-doc.org/en/master/usage/markdown.html

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

docs/conf.py

@@ -35,7 +35,7 @@ master_doc = "index"
 source_suffix = '.rst'
 numfig = True
 
-exclude_patterns = ['build-templates/*.rst']
+exclude_patterns = ['build-templates/*.rst', 'user/*.md']
 
 import searx.engines
 import searx.plugins
@@ -94,7 +94,6 @@ extlinks['pull-searx'] = ('https://github.com/searx/searx/pull/%s', 'PR ')
 # links to custom brand
 extlinks['origin'] = (GIT_URL + '/blob/' + GIT_BRANCH + '/%s', 'git://')
 extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
-extlinks['search'] = (SEARXNG_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', '')
@@ -123,8 +122,11 @@ extensions = [
     'linuxdoc.rstFlatTable',    # Implementation of the 'flat-table' reST-directive.
     'linuxdoc.kfigure',         # Sphinx extension which implements scalable image handling.
     "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs
+    'myst_parser',  # https://www.sphinx-doc.org/en/master/usage/markdown.html
 ]
 
+suppress_warnings = ['myst.domains']
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "flask": ("https://flask.palletsprojects.com/", None),

docs/src/searx.infopage.rst

@@ -0,0 +1,8 @@
+.. _searx.infopage:
+
+================
+Online ``/info``
+================
+
+.. automodule:: searx.infopage
+  :members:

docs/user/.gitignore

@@ -0,0 +1 @@
+*.md

docs/user/index.rst

@@ -2,8 +2,14 @@
 User documentation
 ==================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
+.. contents:: Contents
+   :depth: 3
+   :local:
+   :backlinks: entry
+
+
+.. _search-syntax:
+
+.. include:: search-syntax.md
+   :parser: myst_parser.sphinx_
 
-   search_syntax

docs/user/search_syntax.rst

@@ -1,39 +0,0 @@
-
-.. _search-syntax:
-
-=============
-Search syntax
-=============
-
-SearXNG allows you to modify the default categories, engines and search language
-via the search query.
-
-Prefix ``!``
-  to set Category/engine
-
-Prefix: ``:``
-  to set language
-
-Abbrevations of the engines and languages are also accepted.  Engine/category
-modifiers are chainable and inclusive (e.g. with :search:`!it !ddg !wp qwer
-<?q=%21it%20%21ddg%20%21wp%20qwer>` search in IT category **and** duckduckgo
-**and** wikipedia for ``qwer``).
-
-See the :search:`/preferences page <preferences>` for the list of engines,
-categories and languages.
-
-Examples
-========
-
-Search in wikipedia for ``qwer``:
-
-- :search:`!wp qwer <?q=%21wp%20qwer>` or
-- :search:`!wikipedia qwer :search:<?q=%21wikipedia%20qwer>`
-
-Image search:
-
-- :search:`!images Cthulhu <?q=%21images%20Cthulhu>`
-
-Custom language in wikipedia:
-
-- :search:`:hu !wp hackerspace <?q=%3Ahu%20%21wp%20hackerspace>`