@@ -28,6 +28,9 @@ The sources of Searx's documentation are located at :origin:`docs`. Run
2828 - intersphinx_
2929 - `Sphinx's autodoc`_
3030 - `Sphinx's Python domain`_, `Sphinx's C domain`_
31+ - SVG_, ImageMagick_
32+ - DOT_, `Graphviz's dot`_, Graphviz_
33+
3134
3235.. contents:: Contents
3336 :depth: 3
@@ -76,9 +79,9 @@ Admin's POV: :origin:`docs/admin`
7679
7780Developer's POV: :origin:`docs/dev`
7881 Depending on the readability_ of code, a typical developer is able to read and
79− understand source code. Describe what a item aims to do (e.g. a function),
80− describe chronological order matters, describe it. Name the *out-of-limits
81− condition* and all the side effects a external developer will not know.
82+ understand source code. Describe what a item aims to do (e.g. a function).
83+ If the chronological order matters, describe it. Name the *out-of-limits
84+ conditions* and all the side effects a external developer will not know.
8285
8386.. _reST inline markup:
8487
@@ -254,7 +257,7 @@ Intersphinx is configured in :origin:`docs/conf.py`:
254257 intersphinx_mapping = {
255258 "python": ("https://docs.python.org/3/", None),
256259 "flask": ("https://flask.palletsprojects.com/", None),
257− "jinja": ("https://jinja.palletsprojects.com/", None),
260+ "jinja": ("https://jinja.palletsprojects.com/", None),
258261 "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
259262 "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
260263 }
@@ -298,6 +301,12 @@ Refer to `Sphinx Roles`_ for roles added by Sphinx.
298301Figures & Images
299302================
300303
304+.. sidebar:: Image processing
305+
306+ With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
307+ is flexible. To get best results in the generated output format, install
308+ ImageMagick_ and Graphviz_.
309+
301310Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;
302311scalable in sense of the build process. Normally in absence of a converter
303312tool, the build process will break. From the authors POV it’s annoying to care
@@ -307,36 +316,44 @@ continues and scales output quality in dependence of installed image processors.
307316
308317If you want to add an image, you should use the ``kernel-figure`` and
309318``kernel-image`` directives. E.g. to insert a figure with a scalable image
310−format use SVG (:ref:`svg_image_example`):
319+format use SVG (:ref:`svg image example`):
311320
312321.. code:: reST
313322
314323 .. _svg image example:
315324
316325 .. kernel-figure:: svg_image.svg
317− :alt: simple SVG image
326+ :alt: SVG image example
318327
319− SVG image example
328+ simple SVG image
329+
330+ To refer the figure, a caption block is needed: :ref:`svg image example`.
320331
321332.. _svg image example:
322333
323334.. kernel-figure:: svg_image.svg
324− :alt: simple SVG image
335+ :alt: SVG image example
336+
337+ simple SVG image
325338
326− SVG image example
339+To refer the figure, a caption block is needed: :ref:`svg image example`.
327340
328341DOT files (aka Graphviz)
329342------------------------
330343
331−The kernel figure (and image) directive support **DOT** formated files, see
344+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
345+given.
332346
333−* DOT: http://graphviz.org/pdf/dotguide.pdf
334−* Graphviz: http://www.graphviz.org/content/dot-language
347+- `Graphviz's dot`_
348+- DOT_
349+- Graphviz_
335350
336−A simple example (:ref:`hello_dot_file`):
351+A simple example is shown in :ref:`dot file example`:
337352
338353.. code:: reST
339354
355+ .. _dot file example:
356+
340357 .. kernel-figure:: hello.dot
341358 :alt: hello world
342359
@@ -345,6 +362,8 @@ A simple example (:ref:`hello_dot_file`):
345362.. admonition:: hello.dot
346363 :class: rst-example
347364
365+ .. _dot file example:
366+
348367 .. kernel-figure:: hello.dot
349368 :alt: hello world
350369
@@ -354,77 +373,100 @@ A simple example (:ref:`hello_dot_file`):
354373---------------------
355374
356375Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
357−``kernel-render`` directives.
376+:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
377+shown in figure :ref:`dot render example`:
358378
359−.. code:: reST
379+.. code-block:: rst
360380
361− .. kernel-render:: DOT markup
362− :alt: foobar digraph
363− :caption: Embedded **DOT** (Graphviz) code
381+ .. _dot render example:
382+
383+ .. kernel-render:: DOT
384+ :alt: digraph
385+ :caption: Embedded DOT (Graphviz) code
364386
365387 digraph foo {
366388 "bar" -> "baz";
367389 }
368390
369−How this will be rendered depends on the installed tools. If Graphviz is
370−installed, you will see an vector image. If not the raw markup is inserted as
371−*literal-block* (:ref:`hello_dot_render`).
391+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
392+ render example`.
372393
373−.. admonition:: DOT markup
394+Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
395+installed, you will see an vector image. If not, the raw markup is inserted as
396+*literal-block*.
397+
398+.. admonition:: kernel-render DOT
374399 :class: rst-example
375400
376− .. _hello_dot_render:
401+ .. _dot render example:
377402
378403 .. kernel-render:: DOT
379− :alt: foobar digraph
380− :caption: Embedded **DOT** (Graphviz) code
404+ :alt: digraph
405+ :caption: Embedded DOT (Graphviz) code
381406
382407 digraph foo {
383408 "bar" -> "baz";
384409 }
385410
386−The *render* directive has all the options known from the *figure* directive,
387−plus option ``caption``. If ``caption`` has a value, a *figure* node is
388−inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
389−you want to refer it (:ref:`hello_svg_render`).
390−
411+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
412+ render example`.
391413
392414``kernel-render`` SVG
393415---------------------
394416
395−.. code:: reST
417+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
418+
419+.. code-block:: rst
420+
421+ .. _svg render example:
396422
397− .. kernel-render:: SVG markup
423+ .. kernel-render:: SVG
398424 :caption: Embedded **SVG** markup
399425 :alt: so-nw-arrow
400426..
401427
402− .. code:: xml
428+ .. code:: xml
403429
404430 <?xml version="1.0" encoding="UTF-8"?>
405− <svg xmlns="http://www.w3.org/2000/svg"
406− version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
407− <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
408− <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
431+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
432+ baseProfile="full" width="70px" height="40px"
433+ viewBox="0 0 700 400"
434+ >
435+ <line x1="180" y1="370"
436+ x2="500" y2="50"
437+ stroke="black" stroke-width="15px"
438+ />
439+ <polygon points="585 0 525 25 585 50"
440+ transform="rotate(135 525 25)"
441+ />
409442 </svg>
410443
411−.. admonition:: SVG markup
444+.. admonition:: kernel-render SVG
412445 :class: rst-example
413446
414− .. _hello_svg_render:
447+ .. _svg render example:
415448
416449 .. kernel-render:: SVG
417450 :caption: Embedded **SVG** markup
418451 :alt: so-nw-arrow
419452
420453 <?xml version="1.0" encoding="UTF-8"?>
421− <svg xmlns="http://www.w3.org/2000/svg"
422− version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
423− <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
424− <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
454+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
455+ baseProfile="full" width="70px" height="40px"
456+ viewBox="0 0 700 400"
457+ >
458+ <line x1="180" y1="370"
459+ x2="500" y2="50"
460+ stroke="black" stroke-width="15px"
461+ />
462+ <polygon points="585 0 525 25 585 50"
463+ transform="rotate(135 525 25)"
464+ />
425465 </svg>
426466
427467
468+
469+
428470.. _reST lists:
429471
430472List markups
@@ -551,7 +593,7 @@ are mappings from field names to field bodies. They marked up like this:
551593 :fieldname: Field content
552594 :foo: first paragraph in field foo
553595
554− second paragraph in field foo
596+ second paragraph in field foo
555597
556598 :bar: Field content
557599
@@ -561,7 +603,7 @@ are mappings from field names to field bodies. They marked up like this:
561603 :fieldname: Field content
562604 :foo: first paragraph in field foo
563605
564− second paragraph in field foo
606+ second paragraph in field foo
565607
566608 :bar: Field content
567609
@@ -684,3 +726,9 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
684726.. _docutils: http://docutils.sourceforge.net/docs/index.html
685727.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
686728.. _linuxdoc: https://return42.github.io/linuxdoc
729+.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
730+.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
731+.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
732+.. _Graphviz: https://graphviz.gitlab.io
733+
734+.. _ImageMagick: https://www.imagemagick.org