@@ -11,10 +11,12 @@ reST primer
1111
1212We at searx are using reStructuredText (aka reST_) markup for all kind of
1313documentation, with the builders from the Sphinx_ project a HTML output is
14−generated and deployed at :docs:`github.io <.>`.
14+generated and deployed at :docs:`github.io <.>`. For build prerequisites read
15+:ref:`docs build`.
1516
16−The sources of Searx's documentation are located at :origin:`docs`. Run
17−:ref:`make docs-live <make docs-live>` to build HTML while editing.
17+The source files of Searx's documentation are located at :origin:`docs`. Sphinx
18+assumes source files to be encoded in UTF-8 by defaul. Run :ref:`make docs-live
19+<make docs-live>` to build HTML while editing.
1820
1921.. sidebar:: Further reading
2022
@@ -318,6 +320,123 @@ To list all anchors of the inventory (e.g. ``python``) use:
318320
319321 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
320322
323+Literal blocks
324+==============
325+
326+The simplest form of :duref:`literal-blocks` is a indented block introduced by
327+two colons (``::``). For highlighting use :dudir:`highlight` or :ref:`reST
328+code` directive. To include literals from external files use directive
329+:dudir:`literalinclude`.
330+
331+.. _reST literal:
332+
333+``::``
334+------
335+
336+.. code:: reST
337+
338+ ::
339+
340+ Literal block
341+
342+ Lorem ipsum dolor::
343+
344+ Literal block
345+
346+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
347+ eirmod tempor invidunt ut labore ::
348+
349+ Literal block
350+
351+.. admonition:: Literal block
352+ :class: rst-example
353+
354+ ::
355+
356+ Literal block
357+
358+ Lorem ipsum dolor::
359+
360+ Literal block
361+
362+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
363+ eirmod tempor invidunt ut labore ::
364+
365+ Literal block
366+
367+
368+.. _reST code:
369+
370+``code-block``
371+--------------
372+
373+.. _pygments: https://pygments.org/languages/
374+
375+.. sidebar:: Syntax highlighting
376+
377+ is handled by pygments_.
378+
379+The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
380+with additional options. To learn more about code literals visit
381+:ref:`sphinx:code-examples`.
382+
383+.. code-block:: reST
384+
385+ The URL ``/stats`` handle is shown in :ref:`stats-handle`
386+
387+ .. code-block:: Python
388+ :caption: python code block
389+ :name: stats-handle
390+
391+ @app.route('/stats', methods=['GET'])
392+ def stats():
393+ """Render engine statistics page."""
394+ stats = get_engines_stats()
395+ return render(
396+ 'stats.html'
397+ , stats = stats )
398+
399+.. code-block:: reST
400+
401+.. admonition:: Code block
402+ :class: rst-example
403+
404+ The URL ``/stats`` handle is shown in :ref:`stats-handle`
405+
406+ .. code-block:: Python
407+ :caption: python code block
408+ :name: stats-handle
409+
410+ @app.route('/stats', methods=['GET'])
411+ def stats():
412+ """Render engine statistics page."""
413+ stats = get_engines_stats()
414+ return render(
415+ 'stats.html'
416+ , stats = stats )
417+
418+Unicode substitution
419+====================
420+
421+The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
422+character codes (numerical values) to characters. This directive can only be
423+used within a substitution definition.
424+
425+.. code-block:: reST
426+
427+ .. |copy| unicode:: 0xA9 .. copyright sign
428+ .. |(TM)| unicode:: U+2122
429+
430+ Trademark |(TM)| and copyright |copy| glyphs.
431+
432+.. admonition:: Unicode
433+ :class: rst-example
434+
435+ .. |copy| unicode:: 0xA9 .. copyright sign
436+ .. |(TM)| unicode:: U+2122
437+
438+ Trademark |(TM)| and copyright |copy| glyphs.
439+
321440
322441.. _reST roles:
323442
@@ -351,7 +470,7 @@ The general markup is one of:
351470 :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
352471 :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
353472 :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
354− :rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
473+ math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
355474 :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
356475 :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
357476 :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
@@ -371,16 +490,17 @@ Figures & Images
371490 is flexible. To get best results in the generated output format, install
372491 ImageMagick_ and Graphviz_.
373492
374−Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
375−scalable in sense of the build process. Normally in absence of a converter
493+Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
494+scaleable in sense of the build process. Normally in absence of a converter
376495tool, the build process will break. From the authors POV it’s annoying to care
377496about the build process when handling with images, especially since he has no
378497access to the build process. With :ref:`linuxdoc:kfigure` the build process
379498continues and scales output quality in dependence of installed image processors.
380499
381−If you want to add an image, you should use the ``kernel-figure`` and
382−``kernel-image`` directives. E.g. to insert a figure with a scalable image
383−format use SVG (:ref:`svg image example`):
500+If you want to add an image, you should use the ``kernel-figure`` (inheritance
501+of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
502+directives. E.g. to insert a figure with a scaleable image format use SVG
503+(:ref:`svg image example`):
384504
385505.. code:: reST
386506
@@ -389,7 +509,7 @@ format use SVG (:ref:`svg image example`):
389509 .. kernel-figure:: svg_image.svg
390510 :alt: SVG image example
391511
392− simple SVG image
512+ Simple SVG image
393513
394514 To refer the figure, a caption block is needed: :ref:`svg image example`.
395515
@@ -398,7 +518,7 @@ format use SVG (:ref:`svg image example`):
398518.. kernel-figure:: svg_image.svg
399519 :alt: SVG image example
400520
401− simple SVG image
521+ Simple SVG image.
402522
403523To refer the figure, a caption block is needed: :ref:`svg image example`.
404524
@@ -571,6 +691,35 @@ List markup (:duref:`ref <bullet-lists>`) is simple:
571691 #. It has two items too.
572692
573693
694+Horizontal list
695+---------------
696+
697+The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
698+list.
699+
700+.. code:: reST
701+
702+ .. hlist::
703+
704+ - first list item
705+ - second list item
706+ - third list item
707+ ...
708+
709+.. admonition:: hlist
710+ :class: rst-example
711+
712+ .. hlist::
713+
714+ - first list item
715+ - second list item
716+ - third list item
717+ - next list item
718+ - next list item xxxx
719+ - next list item yyyy
720+ - next list item zzzz
721+
722+
574723Definition list
575724---------------
576725
@@ -1158,70 +1307,84 @@ Tabbed views
11581307
11591308With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
11601309instructions with one tab per distribution we use the `group-tabs`_ directive,
1161−others are basic-tabs_ and code-tabs_.
1162−
1163−
1164−.. code:: reST
1165−
1166− .. tabs::
1167−
1168− .. group-tab:: Linux
1310+others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1311+:ref:`docs build` is shown:
11691312
1170− Linux Line 1
1313+.. literalinclude:: ../admin/buildhosts.rst
1314+ :language: reST
1315+ :start-after: .. _system requirements:
1316+ :end-before: .. _system requirements END:
11711317
1172− .. group-tab:: Mac OSX
11731318
1174− Mac OSX Line 1
1319+.. _math:
11751320
1176− .. group-tab:: Windows
1321+Math equations
1322+==============
11771323
1178− Windows Line 1
1324+.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics
1325+.. _amsmath user guide:
1326+ http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf
11791327
1180− .. tabs::
1328+.. sidebar:: About LaTeX
11811329
1182− .. group-tab:: Linux
1330+ - `amsmath user guide`_
1331+ - Mathematics_
1332+ - :ref:`docs build`
11831333
1184− Linux Line 1
1334+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
1335+package.
11851336
1186− .. group-tab:: Mac OSX
1337+To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
1338+inline and directive :rst:dir:`.. math:: <math>` for block markup.
11871339
1188− Mac OSX Line 1
1340+.. code:: reST
11891341
1190− .. group-tab:: Windows
1342+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1343+ is shown.
11911344
1192− Windows Line 1
1345+ .. math::
1346+ :label: schroedinger general
11931347
1348+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1349+ \hat{H} |\,\psi (t) \rangle.
11941350
1195−.. admonition:: Tabbed view (grouped)
1351+.. admonition:: LaTeX math equation
11961352 :class: rst-example
11971353
1198− .. tabs::
1199−
1200− .. group-tab:: Linux
1201−
1202− Linux Line 1
1203−
1204− .. group-tab:: Mac OSX
1354+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1355+ is shown.
12051356
1206− Mac OSX Line 1
1357+ .. math::
1358+ :label: schroedinger general
12071359
1208− .. group-tab:: Windows
1360+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1361+ \hat{H} |\,\psi (t) \rangle.
12091362
1210− Windows Line 1
12111363
1212− .. tabs::
1364+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1365+(*displaystyle*) used in a inline markup or another fraction.
12131366
1214− .. group-tab:: Linux
1215−
1216− Linux Line 1
1217−
1218− .. group-tab:: Mac OSX
1367+.. code:: reST
12191368
1220− Mac OSX Line 1
1369+ ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
1370+ ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
12211371
1222− .. group-tab:: Windows
1372+.. admonition:: Line spacing
1373+ :class: rst-example
12231374
1224− Windows Line 1
1375+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
1376+ eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
1377+ voluptua. ...
1378+ ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
1379+ At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1380+ gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
1381+
1382+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
1383+ eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
1384+ voluptua. ...
1385+ ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
1386+ At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1387+ gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
12251388
12261389
12271390.. _KISS: https://en.wikipedia.org/wiki/KISS_principle