@@ -11,10 +11,12 @@ reST primer
12We at searx are using reStructuredText (aka reST_) markup for all kind of
12We at searx are using reStructuredText (aka reST_) markup for all kind of
13documentation, with the builders from the Sphinx_ project a HTML output is
13documentation, 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
16−The sources of Searx's documentation are located at :origin:`docs`. Run
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
17−:ref:`make docs-live <make docs-live>` to build HTML while editing.
19+<make docs-live>` to build HTML while editing.
19.. sidebar:: Further reading
21.. sidebar:: Further reading
@@ -318,6 +320,123 @@ To list all anchors of the inventory (e.g. ``python``) use:
319 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
321 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
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`.
346+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
347+ eirmod tempor invidunt ut labore ::
351+.. admonition:: Literal block
362+ Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
363+ eirmod tempor invidunt ut labore ::
373+.. _pygments: https://pygments.org/languages/
375+.. sidebar:: Syntax highlighting
377+ is handled by pygments_.
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`.
385+ The URL ``/stats`` handle is shown in :ref:`stats-handle`
387+ .. code-block:: Python
388+ :caption: python code block
391+ @app.route('/stats', methods=['GET'])
393+ """Render engine statistics page."""
394+ stats = get_engines_stats()
401+.. admonition:: Code block
404+ The URL ``/stats`` handle is shown in :ref:`stats-handle`
406+ .. code-block:: Python
407+ :caption: python code block
410+ @app.route('/stats', methods=['GET'])
412+ """Render engine statistics page."""
413+ stats = get_engines_stats()
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.
427+ .. |copy| unicode:: 0xA9 .. copyright sign
428+ .. |(TM)| unicode:: U+2122
430+ Trademark |(TM)| and copyright |copy| glyphs.
432+.. admonition:: Unicode
435+ .. |copy| unicode:: 0xA9 .. copyright sign
436+ .. |(TM)| unicode:: U+2122
438+ Trademark |(TM)| and copyright |copy| glyphs.
322.. _reST roles:
441.. _reST roles:
@@ -351,7 +470,7 @@ The general markup is one of:
351 :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
470 :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
352 :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
471 :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
353 :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
472 :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```
355 :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
474 :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
356 :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
475 :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
357 :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
476 :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
@@ -371,16 +490,17 @@ Figures & Images
371 is flexible. To get best results in the generated output format, install
490 is flexible. To get best results in the generated output format, install
372 ImageMagick_ and Graphviz_.
491 ImageMagick_ and Graphviz_.
374−Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
493+Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
375−scalable in sense of the build process. Normally in absence of a converter
494+scaleable in sense of the build process. Normally in absence of a converter
376tool, the build process will break. From the authors POV it’s annoying to care
495tool, the build process will break. From the authors POV it’s annoying to care
377about the build process when handling with images, especially since he has no
496about the build process when handling with images, especially since he has no
378access to the build process. With :ref:`linuxdoc:kfigure` the build process
497access to the build process. With :ref:`linuxdoc:kfigure` the build process
379continues and scales output quality in dependence of installed image processors.
498continues and scales output quality in dependence of installed image processors.
381−If you want to add an image, you should use the ``kernel-figure`` and
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`)
382−``kernel-image`` directives. E.g. to insert a figure with a scalable image
502+directives. E.g. to insert a figure with a scaleable image format use SVG
383−format use SVG (:ref:`svg image example`):
503+(:ref:`svg image example`):
385.. code:: reST
505.. code:: reST
@@ -389,7 +509,7 @@ format use SVG (:ref:`svg image example`):
389 .. kernel-figure:: svg_image.svg
509 .. kernel-figure:: svg_image.svg
390 :alt: SVG image example
510 :alt: SVG image example
392− simple SVG image
512+ Simple SVG image
394 To refer the figure, a caption block is needed: :ref:`svg image example`.
514 To refer the figure, a caption block is needed: :ref:`svg image example`.
@@ -398,7 +518,7 @@ format use SVG (:ref:`svg image example`):
398.. kernel-figure:: svg_image.svg
518.. kernel-figure:: svg_image.svg
399 :alt: SVG image example
519 :alt: SVG image example
401− simple SVG image
521+ Simple SVG image.
403To refer the figure, a caption block is needed: :ref:`svg image example`.
523To refer the figure, a caption block is needed: :ref:`svg image example`.
@@ -571,6 +691,35 @@ List markup (:duref:`ref <bullet-lists>`) is simple:
571 #. It has two items too.
691 #. It has two items too.
697+The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
709+.. admonition:: hlist
718+ - next list item xxxx
719+ - next list item yyyy
720+ - next list item zzzz
574Definition list
723Definition list
575---------------
724---------------
@@ -1158,70 +1307,84 @@ Tabbed views
1159With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1308With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1160instructions with one tab per distribution we use the `group-tabs`_ directive,
1309instructions with one tab per distribution we use the `group-tabs`_ directive,
1161−others are basic-tabs_ and code-tabs_.
1310+others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1162−
1311+:ref:`docs build` is shown:
1168− .. group-tab:: Linux
1170− Linux Line 1
1313+.. literalinclude:: ../admin/buildhosts.rst
1315+ :start-after: .. _system requirements:
1316+ :end-before: .. _system requirements END:
1172− .. group-tab:: Mac OSX
1174− Mac OSX Line 1
1319+.. _math:
1176− .. group-tab:: Windows
1321+Math equations
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
1180− .. tabs::
1328+.. sidebar:: About LaTeX
1182− .. group-tab:: Linux
1330+ - `amsmath user guide`_
1332+ - :ref:`docs build`
1184− Linux Line 1
1334+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
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.
1188− Mac OSX Line 1
1340+.. code:: reST
1190− .. group-tab:: Windows
1342+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1192− Windows Line 1
1345+ .. math::
1346+ :label: schroedinger general
1348+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1349+ \hat{H} |\,\psi (t) \rangle.
1195−.. admonition:: Tabbed view (grouped)
1351+.. admonition:: LaTeX math equation
1196 :class: rst-example
1352 :class: rst-example
1198− .. tabs::
1354+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1200− .. group-tab:: Linux
1204− .. group-tab:: Mac OSX
1206− Mac OSX Line 1
1357+ .. math::
1358+ :label: schroedinger general
1208− .. group-tab:: Windows
1360+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1361+ \hat{H} |\,\psi (t) \rangle.
1212− .. tabs::
1364+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1365+(*displaystyle*) used in a inline markup or another fraction.
1214− .. group-tab:: Linux
1367+.. code:: reST
1218− .. group-tab:: Mac OSX
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}`
1222− .. group-tab:: Windows
1372+.. admonition:: Line spacing
1373+ :class: rst-example
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
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.
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
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.
1227.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1390.. _KISS: https://en.wikipedia.org/wiki/KISS_principle