git.iko.soy/searx
on master help sign in
doc: document the new reST & gh-pages workflow
97b86fdMarkus Heiser
docs/conf.py+2
compare with master
unifiedsplit
@@ -6,6 +6,7 @@ from pallets_sphinx_themes import ProjectLink
6
6
7GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx")
7GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx")
8SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me")
8SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me")
9+DOCS_URL = os.environ.get("DOCS_URL", "https://asciimoo.github.io/searx/")
9
10
10# Project --------------------------------------------------------------
11# Project --------------------------------------------------------------
11
12
@@ -30,6 +31,7 @@ extlinks['pull'] = ('https://github.com/asciimoo/searx/pull/%s', 'PR ')
30extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
31extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
31extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
32extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
32extlinks['search'] = (SEARX_URL + '/%s', '#')
33extlinks['search'] = (SEARX_URL + '/%s', '#')
34+extlinks['docs'] = (DOCS_URL + '/%s', 'docs: ')
33
35
34extensions = [
36extensions = [
35 'sphinx.ext.extlinks',
37 'sphinx.ext.extlinks',
docs/dev/contribution_guide.rst+56−3
@@ -82,8 +82,61 @@ Translation currently takes place on :ref:`transifex <translation>`.
82Documentation
82Documentation
83=============
83=============
84
84
85−.. admonition:: ToDo
85+.. _Sphinx: http://www.sphinx-doc.org
86+.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
86
87
87− docs are no longer in gh-branch
88+.. sidebar:: The reST sources
88
89
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