Skip to content

Commit af2cae6

Browse files
return42return42
committed
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>
1 parent 25fa7da commit af2cae6

6 files changed

Lines changed: 43 additions & 25 deletions

File tree

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# -*- coding: utf-8; mode: makefile-gmake -*-
22

3+
export GIT_URL=https://github.com/asciimoo/searx
4+
export SEARX_URL=https://searx.me
5+
36
PYOBJECTS = searx
47
DOC = docs
58
PY_SETUP_EXTRAS ?= \[test\]

‎docs/blog/intro-offline.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Example skeleton for the new engines:
4040
Development progress
4141
--------------------
4242

43-
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
43+
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`.
4444

4545
In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests.
4646

‎docs/conf.py‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
from searx.version import VERSION_STRING
55
from pallets_sphinx_themes import ProjectLink
66

7+
GIT_URL = os.environ.get("GIT_URL", "https://github.com/asciimoo/searx")
8+
SEARX_URL = os.environ.get("SEARX_URL", "https://searx.me")
9+
710
# Project --------------------------------------------------------------
811

912
project = u'searx'
@@ -16,7 +19,16 @@
1619
master_doc = "index"
1720
source_suffix = '.rst'
1821

22+
# usage:: lorem :patch:`f373169` ipsum
23+
24+
extlinks = {}
25+
extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
26+
extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
27+
extlinks['search'] = (SEARX_URL + '/%s', '#')
28+
extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ')
29+
1930
extensions = [
31+
'sphinx.ext.extlinks',
2032
'sphinx.ext.viewcode',
2133
"sphinx.ext.autodoc",
2234
"sphinx.ext.intersphinx",
@@ -43,7 +55,7 @@
4355
html_theme_options = {"index_sidebar_logo": True}
4456
html_context = {
4557
"project_links": [
46-
ProjectLink("Source", os.environ.get("GIT_URL", "https://github.com/asciimoo")),
58+
ProjectLink("Source", GIT_URL),
4759
ProjectLink("Wiki", "https://github.com/asciimoo/searx/wiki"),
4860
ProjectLink("Public instances", "https://github.com/asciimoo/searx/wiki/Searx-instances"),
4961
ProjectLink("Twitter", "https://twitter.com/Searx_engine"),

‎docs/dev/engine_overview.rst‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ so it uses different search engines to provide better results.
88
Because there is no general search API which could be used for every
99
search engine, an adapter has to be built between searx and the
1010
external search engines. Adapters are stored under the folder
11-
`searx/engines
12-
<https://github.com/asciimoo/searx/tree/master/searx/engines>`__.
11+
:origin:`searx/engines`.
1312

1413

1514
.. contents::
@@ -199,7 +198,7 @@ default
199198
+--------------------+---------------------------------------------------------------------------------------------------------------+
200199
| content | string, general result-text |
201200
+--------------------+---------------------------------------------------------------------------------------------------------------+
202-
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish |
201+
| publishedDate | :py:class:`datetime.datetime`, time of publish |
203202
+--------------------+---------------------------------------------------------------------------------------------------------------+
204203

205204
images
@@ -218,7 +217,7 @@ to use this template, the parameter
218217
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
219218
| content | *(partly implemented)* |
220219
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
221-
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(partly implemented)* |
220+
| publishedDate | :py:class:`datetime.datetime`, time of publish *(partly implemented)* |
222221
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
223222
| img\_src | string, url to the result image |
224223
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -239,7 +238,7 @@ videos
239238
+--------------------+--------------------------------------------------------------------------------------------------------------+
240239
| content | *(not implemented yet)* |
241240
+--------------------+--------------------------------------------------------------------------------------------------------------+
242-
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish |
241+
| publishedDate | :py:class:`datetime.datetime`, time of publish |
243242
+--------------------+--------------------------------------------------------------------------------------------------------------+
244243
| thumbnail | string, url to a small-preview image |
245244
+--------------------+--------------------------------------------------------------------------------------------------------------+
@@ -258,7 +257,7 @@ torrent
258257
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
259258
| content | string, general result-text |
260259
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
261-
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(not implemented yet)* |
260+
| publishedDate | :py:class:`datetime.datetime`, time of publish *(not implemented yet)* |
262261
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
263262
| seed | int, number of seeder |
264263
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -286,7 +285,7 @@ map
286285
+-------------------------+--------------------------------------------------------------------------------------------------------------+
287286
| content | string, general result-text |
288287
+-------------------------+--------------------------------------------------------------------------------------------------------------+
289-
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish |
288+
| publishedDate | :py:class:`datetime.datetime`, time of publish |
290289
+-------------------------+--------------------------------------------------------------------------------------------------------------+
291290
| latitude | latitude of result (in decimal format) |
292291
+-------------------------+--------------------------------------------------------------------------------------------------------------+

‎docs/index.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,8 @@ Search without being tracked.
55

66
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.
77

8-
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`.
8+
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`.
99

10-
.. _public instances: https://github.com/asciimoo/searx/wiki/Searx-instances
1110

1211
Features
1312
--------

‎docs/user/search_syntax.rst‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,35 @@ Search syntax
44
Searx allows you to modify the default categories, engines and search
55
language via the search query.
66

7-
Category/engine prefix: ``!``
7+
Prefix ``!``
8+
to set Category/engine
89

9-
Language prefix: ``:``
10+
Prefix: ``:``
11+
to set language
1012

11-
Prefix to add engines and categories to the currently selected
12-
categories: ``?``
13+
Prefix: ``?``
14+
to add engines and categories to the currently selected categories
1315

14-
Abbrevations of the engines and languages are also accepted.
15-
Engine/category modifiers are chainable and inclusive (e.g. with
16-
`!it !ddg !wp qwer <https://searx.me/?q=%21it%20%21ddg%20%21wp%20qwer>`_
17-
search in IT category **and** duckduckgo **and** wikipedia for ``qwer``).
16+
Abbrevations of the engines and languages are also accepted. Engine/category
17+
modifiers are chainable and inclusive (e.g. with :search:`!it !ddg !wp qwer
18+
<?q=%21it%20%21ddg%20%21wp%20qwer>` search in IT category **and** duckduckgo
19+
**and** wikipedia for ``qwer``).
1820

19-
See the `/preferences page <https://searx.me/preferences>`_ for the
20-
list of engines, categories and languages.
21+
See the :search:`/preferences page <preferences>` for the list of engines,
22+
categories and languages.
2123

2224
Examples
2325
~~~~~~~~
2426

2527
Search in wikipedia for ``qwer``:
26-
`!wp qwer <https://searx.me/?q=%21wp%20qwer>`__ or
27-
`!wikipedia qwer <https://searx.me/?q=%21wikipedia%20qwer>`_
28+
29+
- :search:`!wp qwer <?q=%21wp%20qwer>` or
30+
- :search:`!wikipedia qwer :search:<?q=%21wikipedia%20qwer>`
2831

2932
Image search:
30-
`!images Cthulhu <https://searx.me/?q=%21images%20Cthulhu>`_
33+
34+
- :search:`!images Cthulhu <?q=%21images%20Cthulhu>`
3135

3236
Custom language in wikipedia:
33-
`:hu !wp hackerspace <https://searx.me/?q=%3Ahu%20%21wp%20hackerspace>`_
37+
38+
- :search:`:hu !wp hackerspace <?q=%3Ahu%20%21wp%20hackerspace>`

0 commit comments

Comments
 (0)