doc: make use of sphinx.ext.extlinks & sphinx.ext.intersphinx

- add sphinx extensions
- patch documentation to make use of

These modules help to simplify the reST markup of external references.  BTW it
helps to write more readable reST and form custom brands.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

5 files changed, 40 insertions, 25 deletions

diff --git a/docs/blog/intro-offline.rst b/docs/blog/intro-offline.rst
index 914521718..0def3e09a 100644
--- a/docs/blog/intro-offline.rst
+++ b/docs/blog/intro-offline.rst
@@ -40,7 +40,7 @@ Example skeleton for the new engines:
 Development progress
 --------------------
 
-First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: https://github.com/asciimoo/searx/wiki/Offline-engines
+First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: :wiki:`Offline-engines`.
 
 In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests.
 
diff --git a/docs/conf.py b/docs/conf.py
index 1ad1b3b22..ee60e46e3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,6 +4,9 @@ import  sys, os
 from searx.version import VERSION_STRING
 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")
+
 # Project --------------------------------------------------------------
 
 project = u'searx'
@@ -16,7 +19,16 @@ release, version = VERSION_STRING, VERSION_STRING
 master_doc = "index"
 source_suffix = '.rst'
 
+# usage::   lorem :patch:`f373169` ipsum
+
+extlinks = {}
+extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
+extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
+extlinks['search'] = (SEARX_URL + '/%s', '#')
+extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ')
+
 extensions = [
+    'sphinx.ext.extlinks',
     'sphinx.ext.viewcode',
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -43,7 +55,7 @@ html_theme = "searx"
 html_theme_options = {"index_sidebar_logo": True}
 html_context = {
     "project_links": [
-        ProjectLink("Source", os.environ.get("GIT_URL", "https://github.com/asciimoo")),
+        ProjectLink("Source", GIT_URL),
         ProjectLink("Wiki", "https://github.com/asciimoo/searx/wiki"),
         ProjectLink("Public instances", "https://github.com/asciimoo/searx/wiki/Searx-instances"),
         ProjectLink("Twitter", "https://twitter.com/Searx_engine"),
diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst
index a6867b5d0..937ca8880 100644
--- a/docs/dev/engine_overview.rst
+++ b/docs/dev/engine_overview.rst
@@ -8,8 +8,7 @@ so it uses different search engines to provide better results.
 Because there is no general search API which could be used for every
 search engine, an adapter has to be built between searx and the
 external search engines. Adapters are stored under the folder
-`searx/engines
-<https://github.com/asciimoo/searx/tree/master/searx/engines>`__.
+:origin:`searx/engines`.
 
 
 .. contents::
@@ -199,7 +198,7 @@ default
 +--------------------+---------------------------------------------------------------------------------------------------------------+
 | content            | string, general result-text                                                                                   |
 +--------------------+---------------------------------------------------------------------------------------------------------------+
-| publishedDate      | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish     |
+| publishedDate      | :py:class:`datetime.datetime`, time of publish                                                                |
 +--------------------+---------------------------------------------------------------------------------------------------------------+
 
 images
@@ -218,7 +217,7 @@ to use this template, the parameter
 +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | content            | *(partly implemented)*                                                                                                                |
 +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| publishedDate      | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(partly implemented)*      |
+| publishedDate      | :py:class:`datetime.datetime`, time of publish *(partly implemented)*                                                                 |
 +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | img\_src           | string, url to the result image                                                                                                       |
 +--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -239,7 +238,7 @@ videos
 +--------------------+--------------------------------------------------------------------------------------------------------------+
 | content            | *(not implemented yet)*                                                                                      |
 +--------------------+--------------------------------------------------------------------------------------------------------------+
-| publishedDate      | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish    |
+| publishedDate      | :py:class:`datetime.datetime`, time of publish                                                               |
 +--------------------+--------------------------------------------------------------------------------------------------------------+
 | thumbnail          | string, url to a small-preview image                                                                         |
 +--------------------+--------------------------------------------------------------------------------------------------------------+
@@ -258,7 +257,7 @@ torrent
 +------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | content          | string, general result-text                                                                                                           |
 +------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| publishedDate    | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(not implemented yet)*     |
+| publishedDate    | :py:class:`datetime.datetime`, time of publish *(not implemented yet)*                                                                |
 +------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | seed             | int, number of seeder                                                                                                                 |
 +------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -286,7 +285,7 @@ map
 +-------------------------+--------------------------------------------------------------------------------------------------------------+
 | content                 | string, general result-text                                                                                  |
 +-------------------------+--------------------------------------------------------------------------------------------------------------+
-| publishedDate           | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish    |
+| publishedDate           | :py:class:`datetime.datetime`, time of publish                                                               |
 +-------------------------+--------------------------------------------------------------------------------------------------------------+
 | latitude                | latitude of result (in decimal format)                                                                       |
 +-------------------------+--------------------------------------------------------------------------------------------------------------+
diff --git a/docs/index.rst b/docs/index.rst
index 38adf69f2..4b2f170cf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,9 +5,8 @@ Search without being tracked.
 
 Searx is a free internet metasearch engine which aggregates results from more than 70 search services. Users are neither tracked nor profiled. Additionally, searx can be used over Tor for online anonymity.
 
-Get started with searx by using one of the `public instances`_. If you don't trust anyone, you can set up your own, see :ref:`installation`.
+Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`.
 
-.. _public instances: https://github.com/asciimoo/searx/wiki/Searx-instances
 
 Features
 --------
diff --git a/docs/user/search_syntax.rst b/docs/user/search_syntax.rst
index af26ea83c..90f901ba7 100644
--- a/docs/user/search_syntax.rst
+++ b/docs/user/search_syntax.rst
@@ -4,30 +4,35 @@ Search syntax
 Searx allows you to modify the default categories, engines and search
 language via the search query.
 
-Category/engine prefix: ``!``
+Prefix ``!``
+  to set Category/engine
 
-Language prefix: ``:``
+Prefix: ``:``
+  to set language
 
-Prefix to add engines and categories to the currently selected
-categories: ``?``
+Prefix: ``?``
+  to add engines and categories to the currently selected categories
 
-Abbrevations of the engines and languages are also accepted.
-Engine/category modifiers are chainable and inclusive (e.g. with
-`!it !ddg !wp qwer <https://searx.me/?q=%21it%20%21ddg%20%21wp%20qwer>`_
-search in IT category **and** duckduckgo **and** wikipedia for ``qwer``).
+Abbrevations of the engines and languages are also accepted.  Engine/category
+modifiers are chainable and inclusive (e.g. with :search:`!it !ddg !wp qwer
+<?q=%21it%20%21ddg%20%21wp%20qwer>` search in IT category **and** duckduckgo
+**and** wikipedia for ``qwer``).
 
-See the `/preferences page <https://searx.me/preferences>`_ for the
-list of engines, categories and languages.
+See the :search:`/preferences page <preferences>` for the list of engines,
+categories and languages.
 
 Examples
 ~~~~~~~~
 
 Search in wikipedia for ``qwer``:
-`!wp qwer <https://searx.me/?q=%21wp%20qwer>`__ or
-`!wikipedia qwer <https://searx.me/?q=%21wikipedia%20qwer>`_
+
+- :search:`!wp qwer <?q=%21wp%20qwer>` or
+- :search:`!wikipedia qwer :search:<?q=%21wikipedia%20qwer>`
 
 Image search:
-`!images Cthulhu <https://searx.me/?q=%21images%20Cthulhu>`_
+
+- :search:`!images Cthulhu <?q=%21images%20Cthulhu>`
 
 Custom language in wikipedia:
-`:hu !wp hackerspace <https://searx.me/?q=%3Ahu%20%21wp%20hackerspace>`_
+
+- :search:`:hu !wp hackerspace <?q=%3Ahu%20%21wp%20hackerspace>`