@@ -0,0 +1,1428 @@
1+.. _reST primer:
2+
3+===========
4+reST primer
5+===========
6+
7+.. sidebar:: KISS_ and readability_
8+
9+ Instead of defining more and more roles, we at searx encourage our
10+ contributors to follow principles like KISS_ and readability_.
11+
12+We at searx are using reStructuredText (aka reST_) markup for all kind of
13+documentation, with the builders from the Sphinx_ project a HTML output is
14+generated and deployed at :docs:`github.io <.>`. For build prerequisites read
15+:ref:`docs build`.
16+
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.
20+
21+.. sidebar:: Further reading
22+
23+ - Sphinx-Primer_
24+ - `Sphinx markup constructs`_
25+ - reST_, docutils_, `docutils FAQ`_
26+ - Sphinx_, `sphinx-doc FAQ`_
27+ - `sphinx config`_, doctree_
28+ - `sphinx cross references`_
29+ - linuxdoc_
30+ - intersphinx_
31+ - sphinx-jinja_
32+ - `Sphinx's autodoc`_
33+ - `Sphinx's Python domain`_, `Sphinx's C domain`_
34+ - SVG_, ImageMagick_
35+ - DOT_, `Graphviz's dot`_, Graphviz_
36+
37+
38+.. contents:: Contents
39+ :depth: 3
40+ :local:
41+ :backlinks: entry
42+
43+Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is
44+used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
45+
46+.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
47+
48+.. sidebar:: Content matters
49+
50+ The readability_ of the reST sources has its value, therefore we recommend to
51+ make sparse usage of reST markup / .. content matters!
52+
53+**reST** is a plaintext markup language, its markup is *mostly* intuitive and
54+you will not need to learn much to produce well formed articles with. I use the
55+word *mostly*: like everything in live, reST has its advantages and
56+disadvantages, some markups feel a bit grumpy (especially if you are used to
57+other plaintext markups).
58+
59+Soft skills
60+===========
61+
62+Before going any deeper into the markup let's face on some **soft skills** a
63+trained author brings with, to reach a well feedback from readers:
64+
65+- Documentation is dedicated to an audience and answers questions from the
66+ audience point of view.
67+- Don't detail things which are general knowledge from the audience point of
68+ view.
69+- Limit the subject, use cross links for any further reading.
70+
71+To be more concrete what a *point of view* means. In the (:origin:`docs`)
72+folder we have three sections (and the *blog* folder), each dedicate to a
73+different group of audience.
74+
75+User's POV: :origin:`docs/user`
76+ A typical user knows about search engines and might have heard about
77+ meta crawlers and privacy.
78+
79+Admin's POV: :origin:`docs/admin`
80+ A typical Admin knows about setting up services on a linux system, but he does
81+ not know all the pros and cons of a searx setup.
82+
83+Developer's POV: :origin:`docs/dev`
84+ Depending on the readability_ of code, a typical developer is able to read and
85+ understand source code. Describe what a item aims to do (e.g. a function).
86+ If the chronological order matters, describe it. Name the *out-of-limits
87+ conditions* and all the side effects a external developer will not know.
88+
89+.. _reST inline markup:
90+
91+Basic inline markup
92+===================
93+
94+.. sidebar:: Inline markup
95+
96+ - :ref:`reST roles`
97+ - :ref:`reST smart ref`
98+
99+Basic inline markup is done with asterisks and backquotes. If asterisks or
100+backquotes appear in running text and could be confused with inline markup
101+delimiters, they have to be escaped with a backslash (``\*pointer``).
102+
103+.. table:: basic inline markup
104+ :widths: 4 3 7
105+
106+ ================================================ ==================== ========================
107+ description rendered markup
108+ ================================================ ==================== ========================
109+ one asterisk for emphasis *italics* ``*italics*``
110+ two asterisks for strong emphasis **boldface** ``**boldface**``
111+ backquotes for code samples and literals ``foo()`` ````foo()````
112+ quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
113+ ================================================ ==================== ========================
114+
115+.. _reST basic structure:
116+
117+Basic article structure
118+=======================
119+
120+The basic structure of an article makes use of heading adornments to markup
121+chapter, sections and subsections.
122+
123+.. _reST template:
124+
125+reST template
126+-------------
127+
128+reST template for an simple article:
129+
130+.. code:: reST
131+
132+ .. _doc refname:
133+
134+ ==============
135+ Document title
136+ ==============
137+
138+ Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
139+ :ref:`chapter refname`.
140+
141+ .. _chapter refname:
142+
143+ Chapter
144+ =======
145+
146+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
147+ aliquid ex ea commodi consequat ...
148+
149+ .. _section refname:
150+
151+ Section
152+ -------
153+
154+ lorem ..
155+
156+ .. _subsection refname:
157+
158+ Subsection
159+ ~~~~~~~~~~
160+
161+ lorem ..
162+
163+
164+Headings
165+--------
166+
167+#. title - with overline for document title:
168+
169+ .. code:: reST
170+
171+ ==============
172+ Document title
173+ ==============
174+
175+
176+#. chapter - with anchor named ``anchor name``:
177+
178+ .. code:: reST
179+
180+ .. _anchor name:
181+
182+ Chapter
183+ =======
184+
185+#. section
186+
187+ .. code:: reST
188+
189+ Section
190+ -------
191+
192+#. subsection
193+
194+ .. code:: reST
195+
196+ Subsection
197+ ~~~~~~~~~~
198+
199+
200+
201+Anchors & Links
202+===============
203+
204+.. _reST anchor:
205+
206+Anchors
207+-------
208+
209+.. _ref role:
210+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
211+
212+To refer a point in the documentation a anchor is needed. The :ref:`reST
213+template <reST template>` shows an example where a chapter titled *"Chapters"*
214+gets an anchor named ``chapter title``. Another example from *this* document,
215+where the anchor named ``reST anchor``:
216+
217+.. code:: reST
218+
219+ .. _reST anchor:
220+
221+ Anchors
222+ -------
223+
224+ To refer a point in the documentation a anchor is needed ...
225+
226+To refer anchors use the `ref role`_ markup:
227+
228+.. code:: reST
229+
230+ Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
231+ bar <reST anchor>`.
232+
233+.. admonition:: ``:ref:`` role
234+ :class: rst-example
235+
236+ Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
237+ bar <reST anchor>`.
238+
239+.. _reST ordinary ref:
240+
241+Link ordinary URL
242+-----------------
243+
244+If you need to reference external URLs use *named* hyperlinks to maintain
245+readability of reST sources. Here is a example taken from *this* article:
246+
247+.. code:: reST
248+
249+ .. _Sphinx Field Lists:
250+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
251+
252+ With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
253+ readable.
254+
255+ And this shows the alternative (less readable) hyperlink markup `Sphinx Field
256+ Lists
257+ <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
258+
259+.. admonition:: Named hyperlink
260+ :class: rst-example
261+
262+ With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
263+ readable.
264+
265+ And this shows the alternative (less readable) hyperlink markup `Sphinx Field
266+ Lists
267+ <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
268+
269+
270+.. _reST smart ref:
271+
272+Smart refs
273+----------
274+
275+With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
276+content becomes smart.
277+
278+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
279+ :widths: 4 3 7
280+
281+ ========================== ================================== ====================================
282+ refer ... rendered example markup
283+ ========================== ================================== ====================================
284+ :rst:role:`rfc` :rfc:`822` ``:rfc:`822```
285+ :rst:role:`pep` :pep:`8` ``:pep:`8```
286+ sphinx.ext.extlinks_
287+ --------------------------------------------------------------------------------------------------
288+ project's wiki article :wiki:`Offline-engines` ``:wiki:`Offline-engines```
289+ to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
290+ files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
291+ pull request :pull:`1756` ``:pull:`1756```
292+ patch :patch:`af2cae6` ``:patch:`af2cae6```
293+ PyPi package :pypi:`searx` ``:pypi:`searx```
294+ manual page man :man:`bash` ``:man:`bash```
295+ intersphinx_
296+ --------------------------------------------------------------------------------------------------
297+ external anchor :ref:`python:and` ``:ref:`python:and```
298+ external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
299+ python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
300+ flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
301+ ========================== ================================== ====================================
302+
303+
304+Intersphinx is configured in :origin:`docs/conf.py`:
305+
306+.. code:: python
307+
308+ intersphinx_mapping = {
309+ "python": ("https://docs.python.org/3/", None),
310+ "flask": ("https://flask.palletsprojects.com/", None),
311+ "jinja": ("https://jinja.palletsprojects.com/", None),
312+ "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
313+ "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
314+ }
315+
316+
317+To list all anchors of the inventory (e.g. ``python``) use:
318+
319+.. code:: sh
320+
321+ $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
322+
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+
440+
441+.. _reST roles:
442+
443+Roles
444+=====
445+
446+.. sidebar:: Further reading
447+
448+ - `Sphinx Roles`_
449+ - :doc:`sphinx:usage/restructuredtext/domains`
450+
451+
452+A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
453+explicit markup. It signifies that that the enclosed text should be interpreted
454+in a specific way.
455+
456+The general markup is one of:
457+
458+.. code:: reST
459+
460+ :rolename:`ref-name`
461+ :rolename:`ref text <ref-name>`
462+
463+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
464+ :widths: 4 3 7
465+
466+ ========================== ================================== ====================================
467+ role rendered example markup
468+ ========================== ================================== ====================================
469+ :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
470+ :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
471+ :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
472+ :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
473+ math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
474+ :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
475+ :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
476+ :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
477+ :durole:`strong` :strong:`bold` ``:strong:`bold```
478+ :durole:`literal` :literal:`foo()` ``:literal:`foo()```
479+ :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
480+ :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
481+ :durole:`title-reference` :title:`Time` ``:title:`Time```
482+ ========================== ================================== ====================================
483+
484+Figures & Images
485+================
486+
487+.. sidebar:: Image processing
488+
489+ With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
490+ is flexible. To get best results in the generated output format, install
491+ ImageMagick_ and Graphviz_.
492+
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
495+tool, the build process will break. From the authors POV it’s annoying to care
496+about the build process when handling with images, especially since he has no
497+access to the build process. With :ref:`linuxdoc:kfigure` the build process
498+continues and scales output quality in dependence of installed image processors.
499+
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`):
504+
505+.. code:: reST
506+
507+ .. _svg image example:
508+
509+ .. kernel-figure:: svg_image.svg
510+ :alt: SVG image example
511+
512+ Simple SVG image
513+
514+ To refer the figure, a caption block is needed: :ref:`svg image example`.
515+
516+.. _svg image example:
517+
518+.. kernel-figure:: svg_image.svg
519+ :alt: SVG image example
520+
521+ Simple SVG image.
522+
523+To refer the figure, a caption block is needed: :ref:`svg image example`.
524+
525+DOT files (aka Graphviz)
526+------------------------
527+
528+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
529+given.
530+
531+- `Graphviz's dot`_
532+- DOT_
533+- Graphviz_
534+
535+A simple example is shown in :ref:`dot file example`:
536+
537+.. code:: reST
538+
539+ .. _dot file example:
540+
541+ .. kernel-figure:: hello.dot
542+ :alt: hello world
543+
544+ DOT's hello world example
545+
546+.. admonition:: hello.dot
547+ :class: rst-example
548+
549+ .. _dot file example:
550+
551+ .. kernel-figure:: hello.dot
552+ :alt: hello world
553+
554+ DOT's hello world example
555+
556+``kernel-render`` DOT
557+---------------------
558+
559+Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
560+:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
561+shown in figure :ref:`dot render example`:
562+
563+.. code:: reST
564+
565+ .. _dot render example:
566+
567+ .. kernel-render:: DOT
568+ :alt: digraph
569+ :caption: Embedded DOT (Graphviz) code
570+
571+ digraph foo {
572+ "bar" -> "baz";
573+ }
574+
575+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
576+ render example`.
577+
578+Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
579+installed, you will see an vector image. If not, the raw markup is inserted as
580+*literal-block*.
581+
582+.. admonition:: kernel-render DOT
583+ :class: rst-example
584+
585+ .. _dot render example:
586+
587+ .. kernel-render:: DOT
588+ :alt: digraph
589+ :caption: Embedded DOT (Graphviz) code
590+
591+ digraph foo {
592+ "bar" -> "baz";
593+ }
594+
595+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
596+ render example`.
597+
598+``kernel-render`` SVG
599+---------------------
600+
601+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
602+
603+.. code:: reST
604+
605+ .. _svg render example:
606+
607+ .. kernel-render:: SVG
608+ :caption: Embedded **SVG** markup
609+ :alt: so-nw-arrow
610+..
611+
612+ .. code:: xml
613+
614+ <?xml version="1.0" encoding="UTF-8"?>
615+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
616+ baseProfile="full" width="70px" height="40px"
617+ viewBox="0 0 700 400"
618+ >
619+ <line x1="180" y1="370"
620+ x2="500" y2="50"
621+ stroke="black" stroke-width="15px"
622+ />
623+ <polygon points="585 0 525 25 585 50"
624+ transform="rotate(135 525 25)"
625+ />
626+ </svg>
627+
628+.. admonition:: kernel-render SVG
629+ :class: rst-example
630+
631+ .. _svg render example:
632+
633+ .. kernel-render:: SVG
634+ :caption: Embedded **SVG** markup
635+ :alt: so-nw-arrow
636+
637+ <?xml version="1.0" encoding="UTF-8"?>
638+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
639+ baseProfile="full" width="70px" height="40px"
640+ viewBox="0 0 700 400"
641+ >
642+ <line x1="180" y1="370"
643+ x2="500" y2="50"
644+ stroke="black" stroke-width="15px"
645+ />
646+ <polygon points="585 0 525 25 585 50"
647+ transform="rotate(135 525 25)"
648+ />
649+ </svg>
650+
651+
652+
653+
654+.. _reST lists:
655+
656+List markups
657+============
658+
659+Bullet list
660+-----------
661+
662+List markup (:duref:`ref <bullet-lists>`) is simple:
663+
664+.. code:: reST
665+
666+ - This is a bulleted list.
667+
668+ 1. Nested lists are possible, but be aware that they must be separated from
669+ the parent list items by blank line
670+ 2. Second item of nested list
671+
672+ - It has two items, the second
673+ item uses two lines.
674+
675+ #. This is a numbered list.
676+ #. It has two items too.
677+
678+.. admonition:: bullet list
679+ :class: rst-example
680+
681+ - This is a bulleted list.
682+
683+ 1. Nested lists are possible, but be aware that they must be separated from
684+ the parent list items by blank line
685+ 2. Second item of nested list
686+
687+ - It has two items, the second
688+ item uses two lines.
689+
690+ #. This is a numbered list.
691+ #. It has two items too.
692+
693+
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+
723+Definition list
724+---------------
725+
726+.. sidebar:: Note ..
727+
728+ - the term cannot have more than one line of text
729+
730+ - there is **no blank line between term and definition block** // this
731+ distinguishes definition lists (:duref:`ref <definition-lists>`) from block
732+ quotes (:duref:`ref <block-quotes>`).
733+
734+Each definition list (:duref:`ref <definition-lists>`) item contains a term,
735+optional classifiers and a definition. A term is a simple one-line word or
736+phrase. Optional classifiers may follow the term on the same line, each after
737+an inline ' : ' (**space, colon, space**). A definition is a block indented
738+relative to the term, and may contain multiple paragraphs and other body
739+elements. There may be no blank line between a term line and a definition block
740+(*this distinguishes definition lists from block quotes*). Blank lines are
741+required before the first and after the last definition list item, but are
742+optional in-between.
743+
744+Definition lists are created as follows:
745+
746+.. code:: reST
747+
748+ term 1 (up to a line of text)
749+ Definition 1.
750+
751+ See the typo : this line is not a term!
752+
753+ And this is not term's definition. **There is a blank line** in between
754+ the line above and this paragraph. That's why this paragraph is taken as
755+ **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
756+
757+ term 2
758+ Definition 2, paragraph 1.
759+
760+ Definition 2, paragraph 2.
761+
762+ term 3 : classifier
763+ Definition 3.
764+
765+ term 4 : classifier one : classifier two
766+ Definition 4.
767+
768+.. admonition:: definition list
769+ :class: rst-example
770+
771+ term 1 (up to a line of text)
772+ Definition 1.
773+
774+ See the typo : this line is not a term!
775+
776+ And this is not term's definition. **There is a blank line** in between
777+ the line above and this paragraph. That's why this paragraph is taken as
778+ **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
779+
780+
781+ term 2
782+ Definition 2, paragraph 1.
783+
784+ Definition 2, paragraph 2.
785+
786+ term 3 : classifier
787+ Definition 3.
788+
789+ term 4 : classifier one : classifier two
790+
791+
792+Quoted paragraphs
793+-----------------
794+
795+Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
796+them more than the surrounding paragraphs. Line blocks (:duref:`ref
797+<line-blocks>`) are a way of preserving line breaks:
798+
799+.. code:: reST
800+
801+ normal paragraph ...
802+ lorem ipsum.
803+
804+ Quoted paragraph ...
805+ lorem ipsum.
806+
807+ | These lines are
808+ | broken exactly like in
809+ | the source file.
810+
811+
812+.. admonition:: Quoted paragraph and line block
813+ :class: rst-example
814+
815+ normal paragraph ...
816+ lorem ipsum.
817+
818+ Quoted paragraph ...
819+ lorem ipsum.
820+
821+ | These lines are
822+ | broken exactly like in
823+ | the source file.
824+
825+
826+.. _reST field list:
827+
828+Field Lists
829+-----------
830+
831+.. _Sphinx Field Lists:
832+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
833+
834+.. sidebar:: bibliographic fields
835+
836+ First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
837+
838+Field lists are used as part of an extension syntax, such as options for
839+directives, or database-like records meant for further processing. Field lists
840+are mappings from field names to field bodies. They marked up like this:
841+
842+.. code:: reST
843+
844+ :fieldname: Field content
845+ :foo: first paragraph in field foo
846+
847+ second paragraph in field foo
848+
849+ :bar: Field content
850+
851+.. admonition:: Field List
852+ :class: rst-example
853+
854+ :fieldname: Field content
855+ :foo: first paragraph in field foo
856+
857+ second paragraph in field foo
858+
859+ :bar: Field content
860+
861+
862+They are commonly used in Python documentation:
863+
864+.. code:: python
865+
866+ def my_function(my_arg, my_other_arg):
867+ """A function just for me.
868+
869+ :param my_arg: The first of my arguments.
870+ :param my_other_arg: The second of my arguments.
871+
872+ :returns: A message (just for me, of course).
873+ """
874+
875+Further list blocks
876+-------------------
877+
878+- field lists (:duref:`ref <field-lists>`, with caveats noted in
879+ :ref:`reST field list`)
880+- option lists (:duref:`ref <option-lists>`)
881+- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
882+- doctest blocks (:duref:`ref <doctest-blocks>`)
883+
884+
885+Admonitions
886+===========
887+
888+Sidebar
889+-------
890+
891+Sidebar is an eye catcher, often used for admonitions pointing further stuff or
892+site effects. Here is the source of the sidebar :ref:`on top of this page <reST
893+primer>`.
894+
895+.. code:: reST
896+
897+ .. sidebar:: KISS_ and readability_
898+
899+ Instead of defining more and more roles, we at searx encourage our
900+ contributors to follow principles like KISS_ and readability_.
901+
902+Generic admonition
903+------------------
904+
905+The generic :dudir:`admonition <admonitions>` needs a title:
906+
907+.. code:: reST
908+
909+ .. admonition:: generic admonition title
910+
911+ lorem ipsum ..
912+
913+
914+.. admonition:: generic admonition title
915+
916+ lorem ipsum ..
917+
918+
919+Specific admonitions
920+--------------------
921+
922+Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
923+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
924+:dudir:`warning` .
925+
926+.. code:: reST
927+
928+ .. hint::
929+
930+ lorem ipsum ..
931+
932+ .. note::
933+
934+ lorem ipsum ..
935+
936+ .. warning::
937+
938+ lorem ipsum ..
939+
940+
941+.. hint::
942+
943+ lorem ipsum ..
944+
945+.. note::
946+
947+ lorem ipsum ..
948+
949+.. tip::
950+
951+ lorem ipsum ..
952+
953+.. attention::
954+
955+ lorem ipsum ..
956+
957+.. caution::
958+
959+ lorem ipsum ..
960+
961+.. danger::
962+
963+ lorem ipsum ..
964+
965+.. important::
966+
967+ lorem ipsum ..
968+
969+.. error::
970+
971+ lorem ipsum ..
972+
973+.. warning::
974+
975+ lorem ipsum ..
976+
977+
978+Tables
979+======
980+
981+.. sidebar:: Nested tables
982+
983+ Nested tables are ugly! Not all builder support nested tables, don't use
984+ them!
985+
986+ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
987+be comfortable for readers of the text-files, but they have huge disadvantages
988+in the creation and modifying. First, they are hard to edit. Think about
989+adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
990+it is a nightmare on big tables.
991+
992+
993+.. sidebar:: List tables
994+
995+ For meaningful patch and diff use :ref:`reST flat table`.
996+
997+Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
998+cell generates a diff in which also changes are included, which are only
999+ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
1000+here are some helpers:
1001+
1002+* `Emacs Table Mode`_
1003+* `Online Tables Generator`_
1004+
1005+.. _reST simple table:
1006+
1007+Simple tables
1008+-------------
1009+
1010+:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
1011+your table need some metadata (e.g. a title) you need to add the ``.. table::
1012+directive`` :dudir:`(ref) <table>` in front and place the table in its body:
1013+
1014+.. code:: reST
1015+
1016+ .. table:: foo gate truth table
1017+ :widths: grid
1018+ :align: left
1019+
1020+ ====== ====== ======
1021+ Inputs Output
1022+ ------------- ------
1023+ A B A or B
1024+ ====== ====== ======
1025+ False
1026+ --------------------
1027+ True
1028+ --------------------
1029+ True False True
1030+ (foo)
1031+ ------ ------ ------
1032+ False True
1033+ (foo)
1034+ ====== =============
1035+
1036+.. admonition:: Simple ASCII table
1037+ :class: rst-example
1038+
1039+ .. table:: foo gate truth table
1040+ :widths: grid
1041+ :align: left
1042+
1043+ ====== ====== ======
1044+ Inputs Output
1045+ ------------- ------
1046+ A B A or B
1047+ ====== ====== ======
1048+ False
1049+ --------------------
1050+ True
1051+ --------------------
1052+ True False True
1053+ (foo)
1054+ ------ ------ ------
1055+ False True
1056+ (foo)
1057+ ====== =============
1058+
1059+
1060+
1061+.. _reST grid table:
1062+
1063+Grid tables
1064+-----------
1065+
1066+:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
1067+
1068+.. code:: reST
1069+
1070+ .. table:: grid table example
1071+ :widths: 1 1 5
1072+
1073+ +------------+------------+-----------+
1074+ | Header 1 | Header 2 | Header 3 |
1075+ +============+============+===========+
1076+ | body row 1 | column 2 | column 3 |
1077+ +------------+------------+-----------+
1078+ | body row 2 | Cells may span columns.|
1079+ +------------+------------+-----------+
1080+ | body row 3 | Cells may | - Cells |
1081+ +------------+ span rows. | - contain |
1082+ | body row 4 | | - blocks. |
1083+ +------------+------------+-----------+
1084+
1085+.. admonition:: ASCII grid table
1086+ :class: rst-example
1087+
1088+ .. table:: grid table example
1089+ :widths: 1 1 5
1090+
1091+ +------------+------------+-----------+
1092+ | Header 1 | Header 2 | Header 3 |
1093+ +============+============+===========+
1094+ | body row 1 | column 2 | column 3 |
1095+ +------------+------------+-----------+
1096+ | body row 2 | Cells may span columns.|
1097+ +------------+------------+-----------+
1098+ | body row 3 | Cells may | - Cells |
1099+ +------------+ span rows. | - contain |
1100+ | body row 4 | | - blocks. |
1101+ +------------+------------+-----------+
1102+
1103+
1104+.. _reST flat table:
1105+
1106+flat-table
1107+----------
1108+
1109+The ``flat-table`` is a further developed variant of the :ref:`list tables
1110+<linuxdoc:list-table-directives>`. It is a double-stage list similar to the
1111+:dudir:`list-table` with some additional features:
1112+
1113+column-span: ``cspan``
1114+ with the role ``cspan`` a cell can be extended through additional columns
1115+
1116+row-span: ``rspan``
1117+ with the role ``rspan`` a cell can be extended through additional rows
1118+
1119+auto-span:
1120+ spans rightmost cell of a table row over the missing cells on the right side
1121+ of that table-row. With Option ``:fill-cells:`` this behavior can changed
1122+ from *auto span* to *auto fill*, which automatically inserts (empty) cells
1123+ instead of spanning the last cell.
1124+
1125+options:
1126+ :header-rows: [int] count of header rows
1127+ :stub-columns: [int] count of stub columns
1128+ :widths: [[int] [int] ... ] widths of columns
1129+ :fill-cells: instead of auto-span missing cells, insert missing cells
1130+
1131+roles:
1132+ :cspan: [int] additional columns (*morecols*)
1133+ :rspan: [int] additional rows (*morerows*)
1134+
1135+The example below shows how to use this markup. The first level of the staged
1136+list is the *table-row*. In the *table-row* there is only one markup allowed,
1137+the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
1138+and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
1139+
1140+.. code:: reST
1141+
1142+ .. flat-table:: ``flat-table`` example
1143+ :header-rows: 2
1144+ :stub-columns: 1
1145+ :widths: 1 1 1 1 2
1146+
1147+ * - :rspan:`1` head / stub
1148+ - :cspan:`3` head 1.1-4
1149+
1150+ * - head 2.1
1151+ - head 2.2
1152+ - head 2.3
1153+ - head 2.4
1154+
1155+ * .. row body 1 / this is a comment
1156+
1157+ - row 1
1158+ - :rspan:`2` cell 1-3.1
1159+ - cell 1.2
1160+ - cell 1.3
1161+ - cell 1.4
1162+
1163+ * .. Comments and targets are allowed on *table-row* stage.
1164+ .. _`row body 2`:
1165+
1166+ - row 2
1167+ - cell 2.2
1168+ - :rspan:`1` :cspan:`1`
1169+ cell 2.3 with a span over
1170+
1171+ * col 3-4 &
1172+ * row 2-3
1173+
1174+ * - row 3
1175+ - cell 3.2
1176+
1177+ * - row 4
1178+ - cell 4.1
1179+ - cell 4.2
1180+ - cell 4.3
1181+ - cell 4.4
1182+
1183+ * - row 5
1184+ - cell 5.1 with automatic span to rigth end
1185+
1186+ * - row 6
1187+ - cell 6.1
1188+ - ..
1189+
1190+
1191+.. admonition:: List table
1192+ :class: rst-example
1193+
1194+ .. flat-table:: ``flat-table`` example
1195+ :header-rows: 2
1196+ :stub-columns: 1
1197+ :widths: 1 1 1 1 2
1198+
1199+ * - :rspan:`1` head / stub
1200+ - :cspan:`3` head 1.1-4
1201+
1202+ * - head 2.1
1203+ - head 2.2
1204+ - head 2.3
1205+ - head 2.4
1206+
1207+ * .. row body 1 / this is a comment
1208+
1209+ - row 1
1210+ - :rspan:`2` cell 1-3.1
1211+ - cell 1.2
1212+ - cell 1.3
1213+ - cell 1.4
1214+
1215+ * .. Comments and targets are allowed on *table-row* stage.
1216+ .. _`row body 2`:
1217+
1218+ - row 2
1219+ - cell 2.2
1220+ - :rspan:`1` :cspan:`1`
1221+ cell 2.3 with a span over
1222+
1223+ * col 3-4 &
1224+ * row 2-3
1225+
1226+ * - row 3
1227+ - cell 3.2
1228+
1229+ * - row 4
1230+ - cell 4.1
1231+ - cell 4.2
1232+ - cell 4.3
1233+ - cell 4.4
1234+
1235+ * - row 5
1236+ - cell 5.1 with automatic span to rigth end
1237+
1238+ * - row 6
1239+ - cell 6.1
1240+ - ..
1241+
1242+
1243+CSV table
1244+---------
1245+
1246+CSV table might be the choice if you want to include CSV-data from a outstanding
1247+(build) process into your documentation.
1248+
1249+.. code:: reST
1250+
1251+ .. csv-table:: CSV table example
1252+ :header: .. , Column 1, Column 2
1253+ :widths: 2 5 5
1254+ :stub-columns: 1
1255+ :file: csv_table.txt
1256+
1257+Content of file ``csv_table.txt``:
1258+
1259+.. literalinclude:: csv_table.txt
1260+
1261+.. admonition:: CSV table
1262+ :class: rst-example
1263+
1264+ .. csv-table:: CSV table example
1265+ :header: .. , Column 1, Column 2
1266+ :widths: 3 5 5
1267+ :stub-columns: 1
1268+ :file: csv_table.txt
1269+
1270+Templating
1271+==========
1272+
1273+.. sidebar:: Build environment
1274+
1275+ All *generic-doc* tasks are running in the :ref:`build environment <make
1276+ pyenv>`.
1277+
1278+Templating is suitable for documentation which is created generic at the build
1279+time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
1280+environment <make pyenv>` (with searx modules installed). We use this e.g. to
1281+build chapter: :ref:`engines generic`. Below the jinja directive from the
1282+:origin:`docs/admin/engines.rst` is shown:
1283+
1284+.. literalinclude:: ../admin/engines.rst
1285+ :language: reST
1286+ :start-after: .. _configured engines:
1287+
1288+The context for the template is selected in the line ``.. jinja:: webapp``. In
1289+sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
1290+points to the name space of the python module: ``webapp``.
1291+
1292+.. code:: py
1293+
1294+ from searx import webapp
1295+ jinja_contexts = {
1296+ 'webapp': dict(**webapp.__dict__)
1297+ }
1298+
1299+
1300+Tabbed views
1301+============
1302+
1303+.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
1304+.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
1305+.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
1306+.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs
1307+
1308+With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1309+instructions with one tab per distribution we use the `group-tabs`_ directive,
1310+others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1311+:ref:`docs build` is shown:
1312+
1313+.. literalinclude:: ../admin/buildhosts.rst
1314+ :language: reST
1315+ :start-after: .. _system requirements:
1316+ :end-before: .. _system requirements END:
1317+
1318+
1319+.. _math:
1320+
1321+Math equations
1322+==============
1323+
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
1327+
1328+.. sidebar:: About LaTeX
1329+
1330+ - `amsmath user guide`_
1331+ - Mathematics_
1332+ - :ref:`docs build`
1333+
1334+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
1335+package.
1336+
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.
1339+
1340+.. code:: reST
1341+
1342+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1343+ is shown.
1344+
1345+ .. math::
1346+ :label: schroedinger general
1347+
1348+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1349+ \hat{H} |\,\psi (t) \rangle.
1350+
1351+.. admonition:: LaTeX math equation
1352+ :class: rst-example
1353+
1354+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1355+ is shown.
1356+
1357+ .. math::
1358+ :label: schroedinger general
1359+
1360+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1361+ \hat{H} |\,\psi (t) \rangle.
1362+
1363+
1364+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1365+(*displaystyle*) used in a inline markup or another fraction.
1366+
1367+.. code:: reST
1368+
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}`
1371+
1372+.. admonition:: Line spacing
1373+ :class: rst-example
1374+
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.
1388+
1389+
1390+.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1391+
1392+.. _readability: https://docs.python-guide.org/writing/style/
1393+.. _Sphinx-Primer:
1394+ http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
1395+.. _reST: https://docutils.sourceforge.io/rst.html
1396+.. _Sphinx Roles:
1397+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
1398+.. _Sphinx: http://www.sphinx-doc.org
1399+.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html
1400+.. _Sphinx markup constructs:
1401+ http://www.sphinx-doc.org/en/stable/markup/index.html
1402+.. _`sphinx cross references`:
1403+ http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
1404+.. _sphinx.ext.extlinks:
1405+ https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
1406+.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
1407+.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html
1408+.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
1409+.. _Sphinx's Python domain:
1410+ http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
1411+.. _Sphinx's C domain:
1412+ http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
1413+.. _doctree:
1414+ http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
1415+.. _docutils: http://docutils.sourceforge.net/docs/index.html
1416+.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
1417+.. _linuxdoc: https://return42.github.io/linuxdoc
1418+.. _jinja: https://jinja.palletsprojects.com/
1419+.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
1420+.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
1421+.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
1422+.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
1423+.. _Graphviz: https://graphviz.gitlab.io
1424+.. _ImageMagick: https://www.imagemagick.org
1425+
1426+.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
1427+.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables
1428+.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html