From b1912607ae9783d6ccf648bd7706a64eca5bedb9 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Sat, 12 Mar 2022 10:18:08 +0100
Subject: [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                |  6 ++++--
 docs/src/searx.infopage.rst |  8 ++++++++
 docs/user/.gitignore        |  1 +
 docs/user/index.rst         | 14 ++++++++++----
 docs/user/search_syntax.rst | 39 ---------------------------------------
 5 files changed, 23 insertions(+), 45 deletions(-)
 create mode 100644 docs/src/searx.infopage.rst
 create mode 100644 docs/user/.gitignore
 delete mode 100644 docs/user/search_syntax.rst

(limited to 'docs')

diff --git a/docs/conf.py b/docs/conf.py
index 2f58bdb12..89d6bb8f6 100644
--- a/docs/conf.py
+++ b/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),
diff --git a/docs/src/searx.infopage.rst b/docs/src/searx.infopage.rst
new file mode 100644
index 000000000..243e5b0bd
--- /dev/null
+++ b/docs/src/searx.infopage.rst
@@ -0,0 +1,8 @@
+.. _searx.infopage:
+
+================
+Online ``/info``
+================
+
+.. automodule:: searx.infopage
+  :members:
diff --git a/docs/user/.gitignore b/docs/user/.gitignore
new file mode 100644
index 000000000..2e1fa2d52
--- /dev/null
+++ b/docs/user/.gitignore
@@ -0,0 +1 @@
+*.md
\ No newline at end of file
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 0cdb7310c..dc9fb0da2 100644
--- a/docs/user/index.rst
+++ b/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
diff --git a/docs/user/search_syntax.rst b/docs/user/search_syntax.rst
deleted file mode 100644
index 346b3162d..000000000
--- a/docs/user/search_syntax.rst
+++ /dev/null
@@ -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>`
-- 
cgit v1.2.3