From 97b86fd184e81263b818dfd2168385c2e60f327a Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Fri, 13 Dec 2019 14:57:07 +0100
Subject: [PATCH] doc: document the new reST & gh-pages workflow

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/conf.py                    |  2 ++
 docs/dev/contribution_guide.rst | 59 +++++++++++++++++++++++++++++++--
 2 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 5186d0123..c0bd246ac 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -6,6 +6,7 @@ from pallets_sphinx_themes import ProjectLink
 
 GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx")
 SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me")
+DOCS_URL = os.environ.get("DOCS_URL", "https://asciimoo.github.io/searx/")
 
 # Project --------------------------------------------------------------
 
@@ -30,6 +31,7 @@ extlinks['pull'] = ('https://github.com/asciimoo/searx/pull/%s', 'PR ')
 extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
 extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
 extlinks['search'] = (SEARX_URL + '/%s', '#')
+extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
 
 extensions = [
     'sphinx.ext.extlinks',
diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst
index 9414de2c9..22d690033 100644
--- a/docs/dev/contribution_guide.rst
+++ b/docs/dev/contribution_guide.rst
@@ -82,8 +82,61 @@ Translation currently takes place on :ref:`transifex <translation>`.
 Documentation
 =============
 
-.. admonition::  ToDo
+.. _Sphinx: http://www.sphinx-doc.org
+.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
-   docs are no longer in gh-branch
+.. sidebar:: The reST sources
 
-   Update this chapter and document the /docs workflow!!
+   has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
+
+The documentation is built using Sphinx_.  So in order to be able to generate
+the required files, you have to install it on your system.  Much easier, use
+Makefile our targets.
+
+Here is an example which makes complete rebuild:
+
+.. code:: sh
+
+   $ make docs-clean docs
+   ...
+   The HTML pages are in dist/docs.
+
+
+live build
+----------
+
+Live build is like WYSIWYG, If you want to edit the documentation, its
+recommended to use.  The Makefile target ``docs-live`` builds the docs, opens URL
+in your favorite browser and rebuilds every time a reST file has been changed.
+
+.. code:: sh
+
+   $ make docs-clean docs-clean
+   ...
+   The HTML pages are in dist/docs.
+   ... Serving on http://0.0.0.0:8080
+   ... Start watching changes
+
+
+
+deploy on github.io
+-------------------
+
+To deploy documentation at :docs:`github.io <.>` use Makefile target
+``gh-pages``, which will builds the documentation, clones searx into a sub
+folder ``gh-pages``, cleans it, copies the doc build into and runs all the
+needed git add, commit and push:
+
+.. code:: sh
+
+   $ make gh-pages
+   ...
+   SPHINX    docs --> file://<...>/dist/docs
+   The HTML pages are in dist/docs.
+   ...
+   Cloning into 'gh-pages' ...
+   ...
+   cd gh-pages; git checkout gh-pages >/dev/null
+   Switched to a new branch 'gh-pages'
+   ...
+   doc available at --> https://asciimoo.github.io/searx