@@ -0,0 +1,1428 @@
7+.. sidebar:: KISS_ and readability_
9+ Instead of defining more and more roles, we at searx encourage our
10+ contributors to follow principles like KISS_ and readability_.
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
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.
21+.. sidebar:: Further reading
24+ - `Sphinx markup constructs`_
25+ - reST_, docutils_, `docutils FAQ`_
26+ - Sphinx_, `sphinx-doc FAQ`_
27+ - `sphinx config`_, doctree_
28+ - `sphinx cross references`_
32+ - `Sphinx's autodoc`_
33+ - `Sphinx's Python domain`_, `Sphinx's C domain`_
35+ - DOT_, `Graphviz's dot`_, Graphviz_
38+.. contents:: Contents
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]`_.
46+.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
48+.. sidebar:: Content matters
50+ The readability_ of the reST sources has its value, therefore we recommend to
51+ make sparse usage of reST markup / .. content matters!
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).
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:
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
69+- Limit the subject, use cross links for any further reading.
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.
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.
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.
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.
89+.. _reST inline markup:
94+.. sidebar:: Inline markup
97+ - :ref:`reST smart ref`
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``).
103+.. table:: basic inline markup
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+ ================================================ ==================== ========================
115+.. _reST basic structure:
117+Basic article structure
118+=======================
120+The basic structure of an article makes use of heading adornments to markup
121+chapter, sections and subsections.
128+reST template for an simple article:
138+ Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
139+ :ref:`chapter refname`.
141+ .. _chapter refname:
146+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
147+ aliquid ex ea commodi consequat ...
149+ .. _section refname:
156+ .. _subsection refname:
167+#. title - with overline for document title:
176+#. chapter - with anchor named ``anchor name``:
210+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
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``:
224+ To refer a point in the documentation a anchor is needed ...
226+To refer anchors use the `ref role`_ markup:
230+ Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
233+.. admonition:: ``:ref:`` role
236+ Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
239+.. _reST ordinary ref:
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:
249+ .. _Sphinx Field Lists:
250+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
252+ With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
255+ And this shows the alternative (less readable) hyperlink markup `Sphinx Field
257+ <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
259+.. admonition:: Named hyperlink
262+ With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
265+ And this shows the alternative (less readable) hyperlink markup `Sphinx Field
267+ <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
275+With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
276+content becomes smart.
278+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
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:`Searx-instances` ``:wiki:`Searx-instances```
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```
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+ ========================== ================================== ====================================
304+Intersphinx is configured in :origin:`docs/conf.py`:
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),
317+To list all anchors of the inventory (e.g. ``python``) use:
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.
446+.. sidebar:: Further reading
449+ - :doc:`sphinx:usage/restructuredtext/domains`
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
456+The general markup is one of:
460+ :rolename:`ref-name`
461+ :rolename:`ref text <ref-name>`
463+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
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+ ========================== ================================== ====================================
487+.. sidebar:: Image processing
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_.
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.
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`):
507+ .. _svg image example:
509+ .. kernel-figure:: svg_image.svg
510+ :alt: SVG image example
514+ To refer the figure, a caption block is needed: :ref:`svg image example`.
516+.. _svg image example:
518+.. kernel-figure:: svg_image.svg
519+ :alt: SVG image example
523+To refer the figure, a caption block is needed: :ref:`svg image example`.
525+DOT files (aka Graphviz)
526+------------------------
528+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
535+A simple example is shown in :ref:`dot file example`:
539+ .. _dot file example:
541+ .. kernel-figure:: hello.dot
544+ DOT's hello world example
546+.. admonition:: hello.dot
549+ .. _dot file example:
551+ .. kernel-figure:: hello.dot
554+ DOT's hello world example
556+``kernel-render`` DOT
557+---------------------
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`:
565+ .. _dot render example:
567+ .. kernel-render:: DOT
569+ :caption: Embedded DOT (Graphviz) code
575+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
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
582+.. admonition:: kernel-render DOT
585+ .. _dot render example:
587+ .. kernel-render:: DOT
589+ :caption: Embedded DOT (Graphviz) code
595+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
598+``kernel-render`` SVG
599+---------------------
601+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
605+ .. _svg render example:
607+ .. kernel-render:: SVG
608+ :caption: Embedded **SVG** markup
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"
619+ <line x1="180" y1="370"
621+ stroke="black" stroke-width="15px"
623+ <polygon points="585 0 525 25 585 50"
624+ transform="rotate(135 525 25)"
628+.. admonition:: kernel-render SVG
631+ .. _svg render example:
633+ .. kernel-render:: SVG
634+ :caption: Embedded **SVG** markup
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"
642+ <line x1="180" y1="370"
644+ stroke="black" stroke-width="15px"
646+ <polygon points="585 0 525 25 585 50"
647+ transform="rotate(135 525 25)"
662+List markup (:duref:`ref <bullet-lists>`) is simple:
666+ - This is a bulleted list.
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
672+ - It has two items, the second
673+ item uses two lines.
675+ #. This is a numbered list.
676+ #. It has two items too.
678+.. admonition:: bullet list
681+ - This is a bulleted list.
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
687+ - It has two items, the second
688+ item uses two lines.
690+ #. This is a numbered list.
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
728+ - the term cannot have more than one line of text
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>`).
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
744+Definition lists are created as follows:
748+ term 1 (up to a line of text)
751+ See the typo : this line is not a term!
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!
758+ Definition 2, paragraph 1.
760+ Definition 2, paragraph 2.
765+ term 4 : classifier one : classifier two
768+.. admonition:: definition list
771+ term 1 (up to a line of text)
774+ See the typo : this line is not a term!
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!
782+ Definition 2, paragraph 1.
784+ Definition 2, paragraph 2.
789+ term 4 : classifier one : classifier two
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:
801+ normal paragraph ...
804+ Quoted paragraph ...
808+ | broken exactly like in
812+.. admonition:: Quoted paragraph and line block
815+ normal paragraph ...
818+ Quoted paragraph ...
822+ | broken exactly like in
831+.. _Sphinx Field Lists:
832+ https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
834+.. sidebar:: bibliographic fields
836+ First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
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:
844+ :fieldname: Field content
845+ :foo: first paragraph in field foo
847+ second paragraph in field foo
851+.. admonition:: Field List
854+ :fieldname: Field content
855+ :foo: first paragraph in field foo
857+ second paragraph in field foo
862+They are commonly used in Python documentation:
866+ def my_function(my_arg, my_other_arg):
867+ """A function just for me.
869+ :param my_arg: The first of my arguments.
870+ :param my_other_arg: The second of my arguments.
872+ :returns: A message (just for me, of course).
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>`)
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
897+ .. sidebar:: KISS_ and readability_
899+ Instead of defining more and more roles, we at searx encourage our
900+ contributors to follow principles like KISS_ and readability_.
905+The generic :dudir:`admonition <admonitions>` needs a title:
909+ .. admonition:: generic admonition title
914+.. admonition:: generic admonition title
922+Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
923+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
981+.. sidebar:: Nested tables
983+ Nested tables are ugly! Not all builder support nested tables, don't use
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.
993+.. sidebar:: List tables
995+ For meaningful patch and diff use :ref:`reST flat table`.
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:
1002+* `Emacs Table Mode`_
1003+* `Online Tables Generator`_
1005+.. _reST simple table:
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:
1016+ .. table:: foo gate truth table
1020+ ====== ====== ======
1022+ ------------- ------
1024+ ====== ====== ======
1026+ --------------------
1028+ --------------------
1031+ ------ ------ ------
1034+ ====== =============
1036+.. admonition:: Simple ASCII table
1037+ :class: rst-example
1039+ .. table:: foo gate truth table
1043+ ====== ====== ======
1045+ ------------- ------
1047+ ====== ====== ======
1049+ --------------------
1051+ --------------------
1054+ ------ ------ ------
1057+ ====== =============
1061+.. _reST grid table:
1066+:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
1070+ .. table:: grid table example
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+ +------------+------------+-----------+
1085+.. admonition:: ASCII grid table
1086+ :class: rst-example
1088+ .. table:: grid table example
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+ +------------+------------+-----------+
1104+.. _reST flat table:
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:
1113+column-span: ``cspan``
1114+ with the role ``cspan`` a cell can be extended through additional columns
1117+ with the role ``rspan`` a cell can be extended through additional rows
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.
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
1132+ :cspan: [int] additional columns (*morecols*)
1133+ :rspan: [int] additional rows (*morerows*)
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>`).
1142+ .. flat-table:: ``flat-table`` example
1147+ * - :rspan:`1` head / stub
1148+ - :cspan:`3` head 1.1-4
1155+ * .. row body 1 / this is a comment
1158+ - :rspan:`2` cell 1-3.1
1163+ * .. Comments and targets are allowed on *table-row* stage.
1168+ - :rspan:`1` :cspan:`1`
1169+ cell 2.3 with a span over
1184+ - cell 5.1 with automatic span to rigth end
1191+.. admonition:: List table
1192+ :class: rst-example
1194+ .. flat-table:: ``flat-table`` example
1199+ * - :rspan:`1` head / stub
1200+ - :cspan:`3` head 1.1-4
1207+ * .. row body 1 / this is a comment
1210+ - :rspan:`2` cell 1-3.1
1215+ * .. Comments and targets are allowed on *table-row* stage.
1220+ - :rspan:`1` :cspan:`1`
1221+ cell 2.3 with a span over
1236+ - cell 5.1 with automatic span to rigth end
1246+CSV table might be the choice if you want to include CSV-data from a outstanding
1247+(build) process into your documentation.
1251+ .. csv-table:: CSV table example
1252+ :header: .. , Column 1, Column 2
1255+ :file: csv_table.txt
1257+Content of file ``csv_table.txt``:
1259+.. literalinclude:: csv_table.txt
1261+.. admonition:: CSV table
1262+ :class: rst-example
1264+ .. csv-table:: CSV table example
1265+ :header: .. , Column 1, Column 2
1268+ :file: csv_table.txt
1273+.. sidebar:: Build environment
1275+ All *generic-doc* tasks are running in the :ref:`build environment <make
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:
1284+.. literalinclude:: ../admin/engines.rst
1286+ :start-after: .. _configured engines:
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``.
1294+ from searx import webapp
1296+ 'webapp': dict(**webapp.__dict__)
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
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:
1313+.. literalinclude:: ../admin/buildhosts.rst
1315+ :start-after: .. _system requirements:
1316+ :end-before: .. _system requirements END:
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
1328+.. sidebar:: About LaTeX
1330+ - `amsmath user guide`_
1332+ - :ref:`docs build`
1334+The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
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.
1342+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1346+ :label: schroedinger general
1348+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1349+ \hat{H} |\,\psi (t) \rangle.
1351+.. admonition:: LaTeX math equation
1352+ :class: rst-example
1354+ In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1358+ :label: schroedinger general
1360+ \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1361+ \hat{H} |\,\psi (t) \rangle.
1364+The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1365+(*displaystyle*) used in a inline markup or another fraction.
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}`
1372+.. admonition:: Line spacing
1373+ :class: rst-example
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.
1390+.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1392+.. _readability: https://docs.python-guide.org/writing/style/
1394+ http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
1395+.. _reST: https://docutils.sourceforge.io/rst.html
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
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
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