@@ -82,8 +82,61 @@ Translation currently takes place on :ref:`transifex <translation>`.
8282Documentation
8383=============
8484
85−.. admonition:: ToDo
85+.. _Sphinx: http://www.sphinx-doc.org
86+.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
8687
87− docs are no longer in gh-branch
88+.. sidebar:: The reST sources
8889
89− Update this chapter and document the /docs workflow!!
90+ has been moved from ``gh-branch`` into ``master`` (:origin:`docs`).
91+
92+The documentation is built using Sphinx_. So in order to be able to generate
93+the required files, you have to install it on your system. Much easier, use
94+Makefile our targets.
95+
96+Here is an example which makes complete rebuild:
97+
98+.. code:: sh
99+
100+ $ make docs-clean docs
101+ ...
102+ The HTML pages are in dist/docs.
103+
104+
105+live build
106+----------
107+
108+Live build is like WYSIWYG, If you want to edit the documentation, its
109+recommended to use. The Makefile target ``docs-live`` builds the docs, opens URL
110+in your favorite browser and rebuilds every time a reST file has been changed.
111+
112+.. code:: sh
113+
114+ $ make docs-clean docs-clean
115+ ...
116+ The HTML pages are in dist/docs.
117+ ... Serving on http://0.0.0.0:8080
118+ ... Start watching changes
119+
120+
121+
122+deploy on github.io
123+-------------------
124+
125+To deploy documentation at :docs:`github.io <.>` use Makefile target
126+``gh-pages``, which will builds the documentation, clones searx into a sub
127+folder ``gh-pages``, cleans it, copies the doc build into and runs all the
128+needed git add, commit and push:
129+
130+.. code:: sh
131+
132+ $ make gh-pages
133+ ...
134+ SPHINX docs --> file://<...>/dist/docs
135+ The HTML pages are in dist/docs.
136+ ...
137+ Cloning into 'gh-pages' ...
138+ ...
139+ cd gh-pages; git checkout gh-pages >/dev/null
140+ Switched to a new branch 'gh-pages'
141+ ...
142+ doc available at --> https://asciimoo.github.io/searx