From a13d8955bf1091b14768290249d6da128569c3c6 Mon Sep 17 00:00:00 2001
From: Martin Fischer <martin@push-f.com>
Date: Mon, 31 Jan 2022 16:05:59 +0100
Subject: [PATCH] [help] integrate help pages into Sphinx docs

1. move docs/user/index.rst to docs/user_index.rst
2. symlink docs/user/ to searx/help/en/
3. register a sphinx parser for Markdown that uses searx.user_help.render()
4. instance-specific links are linked to go-to-instance.rst
---
 docs/conf.py                            | 50 +++++++++++++++++++++++++
 docs/go-to-instance.rst                 |  7 ++++
 docs/index.rst                          |  2 +-
 docs/user                               |  1 +
 docs/{user/index.rst => user_index.rst} |  3 +-
 5 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 docs/go-to-instance.rst
 create mode 120000 docs/user
 rename docs/{user/index.rst => user_index.rst} (75%)

diff --git a/docs/conf.py b/docs/conf.py
index 2f58bdb12..15af14042 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -3,9 +3,12 @@
 
 import  sys, os
 from pallets_sphinx_themes import ProjectLink
+import docutils.nodes
+import sphinx.parsers
 
 from searx import get_setting
 from searx.version import VERSION_STRING, GIT_URL, GIT_BRANCH
+import searx.user_help
 
 # Project --------------------------------------------------------------
 
@@ -64,6 +67,51 @@ jinja_filters = {
     'group_engines_in_tab': searx.webutils.group_engines_in_tab,
 }
 
+def process_link(href):
+    if href.startswith('/'):
+        return '../go-to-instance.html'
+    else:
+        return href
+
+from searx.webapp import app
+
+MD_VARIABLES = {k: process_link(v) for k,v in searx.user_help.get_variables(app).items()}
+
+class MarkdownParser(sphinx.parsers.Parser):
+    """
+    The user documentation in ``searx/help/en/`` is written in Markdown
+    (and integrated into the web application). This code here lets us host an
+    official version of the user documentation on searxng.org, that we can refer
+    users to (since we don't want to promote a singular instance).
+
+    This class also takes care of defining docutils targets for Markdown files.
+    So for example ``searx/help/en/search-syntax.md`` can be linked to from
+    reStructuredText with ``:ref:`search-syntax```.
+    """
+    supported = ('markdown',)
+
+    def parse(self, inputstring, document):
+        page = searx.user_help.render(inputstring, MD_VARIABLES)
+        pagename = document['source'].split('/')[-1].replace('.md', '')
+        sect = docutils.nodes.section(
+            '',
+            docutils.nodes.title(
+                text=page.title,
+            ),
+            docutils.nodes.raw(
+                text=page.content,
+                format='html',
+            ),
+            ids = [pagename],
+            names = [pagename],
+        )
+        document.children = [sect]
+
+        document.nameids[pagename] = pagename
+        document.nametypes[pagename] = True
+        document.ids[pagename] = sect
+
+
 # Let the Jinja template in configured_engines.rst access documented_modules
 # to automatically link documentation for modules if it exists.
 def setup(app):
@@ -82,6 +130,8 @@ def setup(app):
 
     app.connect('env-before-read-docs', before_read_docs)
     app.connect('source-read', source_read)
+    app.add_source_suffix('.md', 'markdown')
+    app.add_source_parser(MarkdownParser)
 
 # usage::   lorem :patch:`f373169` ipsum
 extlinks = {}
diff --git a/docs/go-to-instance.rst b/docs/go-to-instance.rst
new file mode 100644
index 000000000..1b6c818d9
--- /dev/null
+++ b/docs/go-to-instance.rst
@@ -0,0 +1,7 @@
+:orphan:
+
+=======================
+We cannot link there :(
+=======================
+
+We don't know which instance you're using.
diff --git a/docs/index.rst b/docs/index.rst
index b836f4b4c..494ceb124 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,7 +30,7 @@ If you don't trust anyone, you can set up your own, see :ref:`installation`.
    :maxdepth: 2
    :caption: Contents
 
-   user/index
+   user_index
    own-instance
    admin/index
    dev/index
diff --git a/docs/user b/docs/user
new file mode 120000
index 000000000..51fd818b5
--- /dev/null
+++ b/docs/user
@@ -0,0 +1 @@
+../searx/help/en/
\ No newline at end of file
diff --git a/docs/user/index.rst b/docs/user_index.rst
similarity index 75%
rename from docs/user/index.rst
rename to docs/user_index.rst
index 0cdb7310c..11ff7c466 100644
--- a/docs/user/index.rst
+++ b/docs/user_index.rst
@@ -6,4 +6,5 @@ User documentation
    :maxdepth: 2
    :caption: Contents
 
-   search_syntax
+   user/about
+   user/search-syntax