diff options
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | 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 |