<NME> reST.rst
<BEF> .. _reST primer:

===========
reST primer
===========

.. sidebar:: KISS_ and readability_

   Instead of defining more and more roles, we at searx encourage our
   contributors to follow principles like KISS_ and readability_.

We at searx are using reStructuredText (aka reST_) markup for all kind of
documentation, with the builders from the Sphinx_ project a HTML output is
generated and deployed at :docs:`github.io <.>`.  For build prerequisites read
:ref:`docs build`.
The sources of Searx's documentation are located at :origin:`docs`.  Run
:ref:`make docs-live <make docs-live>` to build HTML while editing.

------

.. sidebar:: Further reading

   - Sphinx-Primer_

   - Sphinx-Primer_
   - `Sphinx markup constructs`_
   - reST_, docutils_, `docutils FAQ`_
   - Sphinx_, `sphinx-doc FAQ`_
   - `sphinx config`_, doctree_
   - `sphinx cross references`_
   - linuxdoc_
   - intersphinx_
   - sphinx-jinja_
   - `Sphinx's autodoc`_
   - `Sphinx's Python domain`_, `Sphinx's C domain`_
   :local:
   :backlinks: entry

------

Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is
used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.

   :local:
   :backlinks: entry

Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is
used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.

.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

.. sidebar:: Content matters

   The readability_ of the reST sources has its value, therefore we recommend to
   make sparse usage of reST markup / .. content matters!

**reST** is a plaintext markup language, its markup is *mostly* intuitive and
you will not need to learn much to produce well formed articles with.  I use the
word *mostly*: like everything in live, reST has its advantages and
disadvantages, some markups feel a bit grumpy (especially if you are used to
other plaintext markups).

Soft skills
===========

Before going any deeper into the markup let's face on some **soft skills** a
trained author brings with, to reach a well feedback from readers:

- Documentation is dedicated to an audience and answers questions from the
  audience point of view.
- Don't detail things which are general knowledge from the audience point of
  view.
- Limit the subject, use cross links for any further reading.

To be more concrete what a *point of view* means.  In the (:origin:`docs`)
folder we have three sections (and the *blog* folder), each dedicate to a
different group of audience.

User's POV: :origin:`docs/user`
  A typical user knows about search engines and might have heard about
  meta crawlers and privacy.

Admin's POV: :origin:`docs/admin`
  A typical Admin knows about setting up services on a linux system, but he does
  not know all the pros and cons of a searx setup.

Developer's POV: :origin:`docs/dev`
  Depending on the readability_ of code, a typical developer is able to read and
  understand source code.  Describe what a item aims to do (e.g. a function).
  If the chronological order matters, describe it.  Name the *out-of-limits
  conditions* and all the side effects a external developer will not know.

.. _reST inline markup:

Basic inline markup
===================

.. sidebar:: Inline markup

   - :ref:`reST roles`
   - :ref:`reST smart ref`

Basic inline markup is done with asterisks and backquotes.  If asterisks or
backquotes appear in running text and could be confused with inline markup
delimiters, they have to be escaped with a backslash (``\*pointer``).

.. table:: basic inline markup
   :widths: 4 3 7

   ================================================ ==================== ========================
   description                                      rendered             markup
   ================================================ ==================== ========================
   one asterisk for emphasis                        *italics*            ``*italics*``
   two asterisks for strong emphasis                **boldface**         ``**boldface**``
   backquotes for code samples and literals         ``foo()``            ````foo()````
   quote asterisks or backquotes                    \*foo is a pointer   ``\*foo is a pointer``
   ================================================ ==================== ========================

.. _reST basic structure:

Basic article structure
=======================

The basic structure of an article makes use of heading adornments to markup
chapter, sections and subsections.

.. _reST template:

reST template
-------------

reST template for an simple article:

.. code:: reST

    .. _doc refname:

    ==============
    Document title
    ==============

    Lorem ipsum dolor sit amet, consectetur adipisici elit ..  Further read
    :ref:`chapter refname`.

    .. _chapter refname:

    Chapter
    =======

    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
    aliquid ex ea commodi consequat ...

    .. _section refname:

    Section
    -------

    lorem ..

    .. _subsection refname:

    Subsection
    ~~~~~~~~~~

    lorem ..


Headings
--------

#. title - with overline for document title:

  .. code:: reST

    ==============
    Document title
    ==============


#. chapter - with anchor named ``anchor name``:

   .. code:: reST

      .. _anchor name:

      Chapter
      =======

#. section

   .. code:: reST

      Section
      -------

#. subsection

   .. code:: reST

      Subsection
      ~~~~~~~~~~



Anchors & Links
===============

.. _reST anchor:

Anchors
-------

.. _ref role:
   https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref

To refer a point in the documentation a anchor is needed.  The :ref:`reST
template <reST template>` shows an example where a chapter titled *"Chapters"*
gets an anchor named ``chapter title``.  Another example from *this* document,
where the anchor named ``reST anchor``:

.. code:: reST

   .. _reST anchor:

   Anchors
   -------

   To refer a point in the documentation a anchor is needed ...

To refer anchors use the `ref role`_ markup:

.. code:: reST

   Visit chapter :ref:`reST anchor`.  Or set hyperlink text manually :ref:`foo
   bar <reST anchor>`.

.. admonition:: ``:ref:`` role
   :class: rst-example

   Visist chapter :ref:`reST anchor`.  Or set hyperlink text manually :ref:`foo
   bar <reST anchor>`.

.. _reST ordinary ref:

Link ordinary URL
-----------------

If you need to reference external URLs use *named* hyperlinks to maintain
readability of reST sources.  Here is a example taken from *this* article:

.. code:: reST

   .. _Sphinx Field Lists:
      https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html

   With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
   readable.

   And this shows the alternative (less readable) hyperlink markup `Sphinx Field
   Lists
   <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.

.. admonition:: Named hyperlink
   :class: rst-example

   With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
   readable.

   And this shows the alternative (less readable) hyperlink markup `Sphinx Field
   Lists
   <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.


.. _reST smart ref:

Smart refs
----------

With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
content becomes smart.

.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
   :widths: 4 3 7

   ========================== ================================== ====================================
   refer ...                  rendered example                   markup
   ========================== ================================== ====================================
   :rst:role:`rfc`            :rfc:`822`                         ``:rfc:`822```
   :rst:role:`pep`            :pep:`8`                           ``:pep:`8```
   sphinx.ext.extlinks_
   --------------------------------------------------------------------------------------------------
   project's wiki article     :wiki:`Offline-engines`            ``:wiki:`Offline-engines```
   to docs public URL         :docs:`dev/reST.html`              ``:docs:`dev/reST.html```
   files & folders origin     :origin:`docs/dev/reST.rst`        ``:origin:`docs/dev/reST.rst```
   pull request               :pull:`1756`                       ``:pull:`1756```
   patch                      :patch:`af2cae6`                   ``:patch:`af2cae6```
   PyPi package               :pypi:`searx`                      ``:pypi:`searx```
   manual page man            :man:`bash`                        ``:man:`bash```
   intersphinx_
   --------------------------------------------------------------------------------------------------
   external anchor            :ref:`python:and`                  ``:ref:`python:and```
   external doc anchor        :doc:`jinja:templates`             ``:doc:`jinja:templates```
   python code object         :py:obj:`datetime.datetime`        ``:py:obj:`datetime.datetime```
   flask code object          :py:obj:`flask.Flask`              ``:py:obj:`flask.Flask```
   ========================== ================================== ====================================


Intersphinx is configured in :origin:`docs/conf.py`:

.. code:: python

    intersphinx_mapping = {
        "python": ("https://docs.python.org/3/", None),
        "flask": ("https://flask.palletsprojects.com/", None),
        "jinja": ("https://jinja.palletsprojects.com/", None),
        "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
        "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
    }


To list all anchors of the inventory (e.g. ``python``) use:

.. code:: sh

   $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
   ...
   $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
   ...

Literal blocks
==============

The simplest form of :duref:`literal-blocks` is a indented block introduced by
two colons (``::``).  For highlighting use :dudir:`highlight` or :ref:`reST
code` directive.  To include literals from external files use
:rst:dir:`literalinclude` or :ref:`kernel-include <kernel-include-directive>`
directive (latter one expands environment variables in the path name).

.. _reST literal:

``::``
------

.. code:: reST

   ::

     Literal block

   Lorem ipsum dolor::

     Literal block

   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
   eirmod tempor invidunt ut labore ::

     Literal block

.. admonition:: Literal block
   :class: rst-example

   ::

     Literal block

   Lorem ipsum dolor::

     Literal block

   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
   eirmod tempor invidunt ut labore ::

     Literal block


.. _reST code:

``code-block``
--------------

.. _pygments: https://pygments.org/languages/

.. sidebar:: Syntax highlighting

   is handled by pygments_.

The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
with additional options.  To learn more about code literals visit
:ref:`sphinx:code-examples`.

.. code-block:: reST

   The URL ``/stats`` handle is shown in :ref:`stats-handle`

   .. code-block:: Python
      :caption: python code block
      :name: stats-handle

      @app.route('/stats', methods=['GET'])
      def stats():
          """Render engine statistics page."""
          stats = get_engines_stats()
          return render(
              'stats.html'
              , stats = stats )

.. code-block:: reST

.. admonition:: Code block
   :class: rst-example

   The URL ``/stats`` handle is shown in :ref:`stats-handle`

   .. code-block:: Python
      :caption: python code block
      :name: stats-handle

      @app.route('/stats', methods=['GET'])
      def stats():
          """Render engine statistics page."""
          stats = get_engines_stats()
          return render(
              'stats.html'
              , stats = stats )

Unicode substitution
====================

The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
character codes (numerical values) to characters.  This directive can only be
used within a substitution definition.

.. code-block:: reST

   .. |copy| unicode:: 0xA9 .. copyright sign
   .. |(TM)| unicode:: U+2122

   Trademark |(TM)| and copyright |copy| glyphs.

.. admonition:: Unicode
   :class: rst-example

   .. |copy| unicode:: 0xA9 .. copyright sign
   .. |(TM)| unicode:: U+2122

   Trademark |(TM)| and copyright |copy| glyphs.


.. _reST roles:

Roles
=====

.. sidebar:: Further reading

   - `Sphinx Roles`_
   - :doc:`sphinx:usage/restructuredtext/domains`


A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
explicit markup.  It signifies that that the enclosed text should be interpreted
in a specific way.

The general markup is one of:

.. code:: reST

   :rolename:`ref-name`
   :rolename:`ref text <ref-name>`

.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
   :widths: 4 3 7

   ========================== ================================== ====================================
   role                       rendered example                   markup
   ========================== ================================== ====================================
   :rst:role:`guilabel`       :guilabel:`&Cancel`                ``:guilabel:`&Cancel```
   :rst:role:`kbd`            :kbd:`C-x C-f`                     ``:kbd:`C-x C-f```
   :rst:role:`menuselection`  :menuselection:`Open --> File`     ``:menuselection:`Open --> File```
   :rst:role:`download`       :download:`this file <reST.rst>`   ``:download:`this file <reST.rst>```
   math_                      :math:`a^2 + b^2 = c^2`            ``:math:`a^2 + b^2 = c^2```
   :rst:role:`ref`            :ref:`svg image example`           ``:ref:`svg image example```
   :rst:role:`command`        :command:`ls -la`                  ``:command:`ls -la```
   :durole:`emphasis`         :emphasis:`italic`                 ``:emphasis:`italic```
   :durole:`strong`           :strong:`bold`                     ``:strong:`bold```
   :durole:`literal`          :literal:`foo()`                   ``:literal:`foo()```
   :durole:`subscript`        H\ :sub:`2`\ O                     ``H\ :sub:`2`\ O``
   :durole:`superscript`      E = mc\ :sup:`2`                   ``E = mc\ :sup:`2```
   :durole:`title-reference`  :title:`Time`                      ``:title:`Time```
   ========================== ================================== ====================================

Figures & Images
================

.. sidebar:: Image processing

   With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
   is flexible.  To get best results in the generated output format, install
   ImageMagick_ and Graphviz_.

Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`.  Scalable here means;
scalable in sense of the build process.  Normally in absence of a converter
tool, the build process will break.  From the authors POV it’s annoying to care
about the build process when handling with images, especially since he has no
access to the build process.  With :ref:`linuxdoc:kfigure` the build process
continues and scales output quality in dependence of installed image processors.

If you want to add an image, you should use the ``kernel-figure`` (inheritance
of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
directives.  E.g. to insert a figure with a scalable image format use SVG
(:ref:`svg image example`):

.. code:: reST

   .. _svg image example:

   .. kernel-figure:: svg_image.svg
      :alt: SVG image example

      Simple SVG image

    To refer the figure, a caption block is needed: :ref:`svg image example`.

.. _svg image example:

.. kernel-figure:: svg_image.svg
   :alt: SVG image example

   Simple SVG image.

To refer the figure, a caption block is needed: :ref:`svg image example`.

DOT files (aka Graphviz)
------------------------

With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
given.

- `Graphviz's dot`_
- DOT_
- Graphviz_

A simple example is shown in :ref:`dot file example`:

.. code:: reST

   .. _dot file example:

   .. kernel-figure:: hello.dot
      :alt: hello world

      DOT's hello world example

.. admonition:: hello.dot
   :class: rst-example

   .. _dot file example:

   .. kernel-figure:: hello.dot
      :alt: hello world

      DOT's hello world example

``kernel-render`` DOT
---------------------

Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
:ref:`linuxdoc:kernel-render` directive.  A simple example of embedded DOT_ is
shown in figure :ref:`dot render example`:

.. code:: reST

   .. _dot render example:

   .. kernel-render:: DOT
      :alt: digraph
      :caption: Embedded  DOT (Graphviz) code

      digraph foo {
        "bar" -> "baz";
      }

   Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
   render example`.

Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`.  If Graphviz_ is
installed, you will see an vector image.  If not, the raw markup is inserted as
*literal-block*.

.. admonition:: kernel-render DOT
   :class: rst-example

- doctest blocks (:duref:`ref <doctest-blocks>`)


.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
.. _readability: https://docs.python-guide.org/writing/style/
.. _Sphinx-Primer:
Bullet list
-----------

List markup (:duref:`ref <bullet-lists>`) is simple:

.. code:: reST

   - This is a bulleted list.

     1. Nested lists are possible, but be aware that they must be separated from
        the parent list items by blank line
     2. Second item of nested list

   - It has two items, the second
     item uses two lines.

   #. This is a numbered list.
   #. It has two items too.

.. admonition:: bullet list
   :class: rst-example

   - This is a bulleted list.

     1. Nested lists are possible, but be aware that they must be separated from
        the parent list items by blank line
     2. Second item of nested list

   - It has two items, the second
     item uses two lines.

   #. This is a numbered list.
   #. It has two items too.


Horizontal list
---------------

The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
list.

.. code:: reST

   .. hlist::

      - first list item
      - second list item
      - third list item
      ...

.. admonition:: hlist
   :class: rst-example

   .. hlist::

      - first list item
      - second list item
      - third list item
      - next list item
      - next list item xxxx
      - next list item yyyy
      - next list item zzzz


Definition list
---------------

.. sidebar:: Note ..

   - the term cannot have more than one line of text

   - there is **no blank line between term and definition block** // this
     distinguishes definition lists (:duref:`ref <definition-lists>`) from block
     quotes (:duref:`ref <block-quotes>`).

Each definition list (:duref:`ref <definition-lists>`) item contains a term,
optional classifiers and a definition.  A term is a simple one-line word or
phrase.  Optional classifiers may follow the term on the same line, each after
an inline ' : ' (**space, colon, space**).  A definition is a block indented
relative to the term, and may contain multiple paragraphs and other body
elements.  There may be no blank line between a term line and a definition block
(*this distinguishes definition lists from block quotes*).  Blank lines are
required before the first and after the last definition list item, but are
optional in-between.

Definition lists are created as follows:

.. code:: reST

   term 1 (up to a line of text)
       Definition 1.

   See the typo : this line is not a term!

     And this is not term's definition.  **There is a blank line** in between
     the line above and this paragraph.  That's why this paragraph is taken as
     **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!

   term 2
       Definition 2, paragraph 1.

       Definition 2, paragraph 2.

   term 3 : classifier
       Definition 3.

   term 4 : classifier one : classifier two
       Definition 4.

.. admonition:: definition list
   :class: rst-example

   term 1 (up to a line of text)
       Definition 1.

   See the typo : this line is not a term!

     And this is not term's definition.  **There is a blank line** in between
     the line above and this paragraph.  That's why this paragraph is taken as
     **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!


   term 2
       Definition 2, paragraph 1.

       Definition 2, paragraph 2.

   term 3 : classifier
       Definition 3.

   term 4 : classifier one : classifier two


Quoted paragraphs
-----------------

Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
them more than the surrounding paragraphs.  Line blocks (:duref:`ref
<line-blocks>`) are a way of preserving line breaks:

.. code:: reST

   normal paragraph ...
   lorem ipsum.

      Quoted paragraph ...
      lorem ipsum.

   | These lines are
   | broken exactly like in
   | the source file.


.. admonition:: Quoted paragraph and line block
   :class: rst-example

   normal paragraph ...
   lorem ipsum.

      Quoted paragraph ...
      lorem ipsum.

   | These lines are
   | broken exactly like in
   | the source file.


.. _reST field list:

Field Lists
-----------

.. _Sphinx Field Lists:
   https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html

.. sidebar::  bibliographic fields

   First lines fields are bibliographic fields, see `Sphinx Field Lists`_.

Field lists are used as part of an extension syntax, such as options for
directives, or database-like records meant for further processing.  Field lists
are mappings from field names to field bodies.  They marked up like this:

.. code:: reST

   :fieldname: Field content
   :foo:       first paragraph in field foo

               second paragraph in field foo

   :bar:       Field content

.. admonition:: Field List
   :class: rst-example

   :fieldname: Field content
   :foo:       first paragraph in field foo

               second paragraph in field foo

   :bar:       Field content


They are commonly used in Python documentation:

.. code:: python

   def my_function(my_arg, my_other_arg):
       """A function just for me.

       :param my_arg: The first of my arguments.
       :param my_other_arg: The second of my arguments.

       :returns: A message (just for me, of course).
       """

Further list blocks
-------------------

- field lists (:duref:`ref <field-lists>`, with caveats noted in
  :ref:`reST field list`)
- option lists (:duref:`ref <option-lists>`)
- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
- doctest blocks (:duref:`ref <doctest-blocks>`)


Admonitions
===========

Sidebar
-------

Sidebar is an eye catcher, often used for admonitions pointing further stuff or
site effects.  Here is the source of the sidebar :ref:`on top of this page <reST
primer>`.

.. code:: reST

   .. sidebar:: KISS_ and readability_

      Instead of defining more and more roles, we at searx encourage our
      contributors to follow principles like KISS_ and readability_.

Generic admonition
------------------

The generic :dudir:`admonition <admonitions>` needs a title:

.. code:: reST

   .. admonition:: generic admonition title

      lorem ipsum ..


.. admonition:: generic admonition title

   lorem ipsum ..


Specific admonitions
--------------------

Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
:dudir:`warning` .

.. code:: reST

   .. hint::

      lorem ipsum ..

   .. note::

      lorem ipsum ..

   .. warning::

      lorem ipsum ..


.. hint::

   lorem ipsum ..

.. note::

   lorem ipsum ..

.. tip::

   lorem ipsum ..

.. attention::

   lorem ipsum ..

.. caution::

   lorem ipsum ..

.. danger::

   lorem ipsum ..

.. important::

   lorem ipsum ..

.. error::

   lorem ipsum ..

.. warning::

   lorem ipsum ..


Tables
======

.. sidebar:: Nested tables

   Nested tables are ugly! Not all builder support nested tables, don't use
   them!

ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
be comfortable for readers of the text-files, but they have huge disadvantages
in the creation and modifying.  First, they are hard to edit.  Think about
adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
it is a nightmare on big tables.


.. sidebar:: List tables

   For meaningful patch and diff use :ref:`reST flat table`.

Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
cell generates a diff in which also changes are included, which are only
ascribable to the ASCII-art.  Anyway, if you prefer ASCII-art for any reason,
here are some helpers:

* `Emacs Table Mode`_
* `Online Tables Generator`_

.. _reST simple table:

Simple tables
-------------

:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*.  If
your table need some metadata (e.g. a title) you need to add the ``.. table::
directive`` :dudir:`(ref) <table>` in front and place the table in its body:

.. code:: reST

   .. table:: foo gate truth table
      :widths: grid
      :align: left

      ====== ====== ======
          Inputs    Output
      ------------- ------
      A      B      A or B
      ====== ====== ======
      False
      --------------------
      True
      --------------------
      True   False  True
             (foo)
      ------ ------ ------
      False  True
             (foo)
      ====== =============

.. admonition:: Simple ASCII table
   :class: rst-example

   .. table:: foo gate truth table
      :widths: grid
      :align: left

      ====== ====== ======
          Inputs    Output
      ------------- ------
      A      B      A or B
      ====== ====== ======
      False
      --------------------
      True
      --------------------
      True   False  True
             (foo)
      ------ ------ ------
      False  True
             (foo)
      ====== =============



.. _reST grid table:

Grid tables
-----------

:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:

.. code:: reST

   .. table:: grid table example
      :widths: 1 1 5

      +------------+------------+-----------+
      | Header 1   | Header 2   | Header 3  |
      +============+============+===========+
      | body row 1 | column 2   | column 3  |
      +------------+------------+-----------+
      | body row 2 | Cells may span columns.|
      +------------+------------+-----------+
      | body row 3 | Cells may  | - Cells   |
      +------------+ span rows. | - contain |
      | body row 4 |            | - blocks. |
      +------------+------------+-----------+

.. admonition:: ASCII grid table
   :class: rst-example

   .. table:: grid table example
      :widths: 1 1 5

      +------------+------------+-----------+
      | Header 1   | Header 2   | Header 3  |
      +============+============+===========+
      | body row 1 | column 2   | column 3  |
      +------------+------------+-----------+
      | body row 2 | Cells may span columns.|
      +------------+------------+-----------+
      | body row 3 | Cells may  | - Cells   |
      +------------+ span rows. | - contain |
      | body row 4 |            | - blocks. |
      +------------+------------+-----------+


.. _reST flat table:

flat-table
----------

The ``flat-table`` is a further developed variant of the :ref:`list tables
<linuxdoc:list-table-directives>`.  It is a double-stage list similar to the
:dudir:`list-table` with some additional features:

column-span: ``cspan``
  with the role ``cspan`` a cell can be extended through additional columns

row-span: ``rspan``
  with the role ``rspan`` a cell can be extended through additional rows

auto-span:
  spans rightmost cell of a table row over the missing cells on the right side
  of that table-row.  With Option ``:fill-cells:`` this behavior can changed
  from *auto span* to *auto fill*, which automatically inserts (empty) cells
  instead of spanning the last cell.

options:
  :header-rows:   [int] count of header rows
  :stub-columns:  [int] count of stub columns
  :widths:        [[int] [int] ... ] widths of columns
  :fill-cells:    instead of auto-span missing cells, insert missing cells

roles:
  :cspan: [int] additional columns (*morecols*)
  :rspan: [int] additional rows (*morerows*)

The example below shows how to use this markup.  The first level of the staged
list is the *table-row*. In the *table-row* there is only one markup allowed,
the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).

.. code:: reST

   .. flat-table:: ``flat-table`` example
      :header-rows: 2
      :stub-columns: 1
      :widths: 1 1 1 1 2

      * - :rspan:`1` head / stub
        - :cspan:`3` head 1.1-4

      * - head 2.1
        - head 2.2
        - head 2.3
        - head 2.4

      * .. row body 1 / this is a comment

        - row 1
        - :rspan:`2` cell 1-3.1
        - cell 1.2
        - cell 1.3
        - cell 1.4

      * .. Comments and targets are allowed on *table-row* stage.
        .. _`row body 2`:

        - row 2
        - cell 2.2
        - :rspan:`1` :cspan:`1`
          cell 2.3 with a span over

          * col 3-4 &
          * row 2-3

      * - row 3
        - cell 3.2

      * - row 4
        - cell 4.1
        - cell 4.2
        - cell 4.3
        - cell 4.4

      * - row 5
        - cell 5.1 with automatic span to right end

      * - row 6
        - cell 6.1
        - ..


.. admonition:: List table
   :class: rst-example

   .. flat-table:: ``flat-table`` example
      :header-rows: 2
      :stub-columns: 1
      :widths: 1 1 1 1 2

      * - :rspan:`1` head / stub
        - :cspan:`3` head 1.1-4

      * - head 2.1
        - head 2.2
        - head 2.3
        - head 2.4

      * .. row body 1 / this is a comment

        - row 1
        - :rspan:`2` cell 1-3.1
        - cell 1.2
        - cell 1.3
        - cell 1.4

      * .. Comments and targets are allowed on *table-row* stage.
        .. _`row body 2`:

        - row 2
        - cell 2.2
        - :rspan:`1` :cspan:`1`
          cell 2.3 with a span over

          * col 3-4 &
          * row 2-3

      * - row 3
        - cell 3.2

      * - row 4
        - cell 4.1
        - cell 4.2
        - cell 4.3
        - cell 4.4

      * - row 5
        - cell 5.1 with automatic span to right end

      * - row 6
        - cell 6.1
        - ..


CSV table
---------

CSV table might be the choice if you want to include CSV-data from a outstanding
(build) process into your documentation.

.. code:: reST

   .. csv-table:: CSV table example
      :header: .. , Column 1, Column 2
      :widths: 2 5 5
      :stub-columns: 1
      :file: csv_table.txt

Content of file ``csv_table.txt``:

.. literalinclude:: csv_table.txt

.. admonition:: CSV table
   :class: rst-example

   .. csv-table:: CSV table example
      :header: .. , Column 1, Column 2
      :widths: 3 5 5
      :stub-columns: 1
      :file: csv_table.txt

Templating
==========

.. sidebar:: Build environment

   All *generic-doc* tasks are running in the :ref:`make install`.

Templating is suitable for documentation which is created generic at the build
time.  The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`make
install` (with searx modules installed).  We use this e.g. to build chapter:
:ref:`engines generic`.  Below the jinja directive from the
:origin:`docs/admin/engines.rst` is shown:

.. literalinclude:: ../admin/engines.rst
   :language: reST
   :start-after: .. _configured engines:

The context for the template is selected in the line ``.. jinja:: searx``.  In
sphinx's build configuration (:origin:`docs/conf.py`) the ``searx`` context
contains the ``engines`` and ``plugins``.

.. code:: py

   import searx.search
   import searx.engines
   import searx.plugins
   searx.search.initialize()
   jinja_contexts = {
      'searx': {
         'engines': searx.engines.engines,
         'plugins': searx.plugins.plugins
      },
   }


Tabbed views
============

.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs

With `sphinx-tabs`_ extension we have *tabbed views*.  To provide installation
instructions with one tab per distribution we use the `group-tabs`_ directive,
others are basic-tabs_ and code-tabs_.  Below a *group-tab* example from
:ref:`docs build` is shown:

.. literalinclude:: ../admin/buildhosts.rst
   :language: reST
   :start-after: .. SNIP sh lint requirements
   :end-before: .. SNAP sh lint requirements

.. _math:

Math equations
==============

.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics
.. _amsmath user guide:
   http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf

.. sidebar:: About LaTeX

   - `amsmath user guide`_
   - Mathematics_
   - :ref:`docs build`

The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
package.

To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
inline and directive :rst:dir:`.. math:: <math>` for block markup.

.. code:: reST

   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
   is shown.

   .. math::
      :label: schroedinger general

       \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
             \hat{H} |\,\psi (t) \rangle.

.. admonition:: LaTeX math equation
   :class: rst-example

   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
   is shown.

   .. math::
      :label: schroedinger general

       \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
             \hat{H} |\,\psi (t) \rangle.


The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
(*displaystyle*) used in a inline markup or another fraction.

.. code:: reST

   ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
   ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`

.. admonition:: Line spacing
   :class: rst-example

   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
   voluptua.  ...
   ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
   At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
   gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
   voluptua.  ...
   ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
   At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
   gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.


.. _KISS: https://en.wikipedia.org/wiki/KISS_principle

.. _readability: https://docs.python-guide.org/writing/style/
.. _Sphinx-Primer:
    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _reST: https://docutils.sourceforge.io/rst.html
.. _Sphinx Roles:
    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
.. _Sphinx: https://www.sphinx-doc.org
.. _`sphinx-doc FAQ`: https://www.sphinx-doc.org/en/stable/faq.html
.. _Sphinx markup constructs:
    https://www.sphinx-doc.org/en/stable/markup/index.html
.. _`sphinx cross references`:
    https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
.. _sphinx.ext.extlinks:
    https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
.. _sphinx config: https://www.sphinx-doc.org/en/stable/config.html
.. _Sphinx's autodoc: https://www.sphinx-doc.org/en/stable/ext/autodoc.html
.. _Sphinx's Python domain:
    https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
.. _Sphinx's C domain:
   https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
.. _doctree:
    https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
.. _docutils: http://docutils.sourceforge.net/docs/index.html
.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
.. _linuxdoc: https://return42.github.io/linuxdoc
.. _jinja: https://jinja.palletsprojects.com/
.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
.. _Graphviz: https://graphviz.gitlab.io
.. _ImageMagick: https://www.imagemagick.org

.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
.. _`Online Tables Generator`: https://www.tablesgenerator.com/text_tables
.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html

<MSG> doc: reST primer -- describe admonitions & customize their CSS

Signed-off-by: Markus Heiser <14dfd67dd72e7ac80c040b62bb932f1e121795cc@darmarit.de>

<DFF> @@ -16,8 +16,6 @@ generated and deployed at :docs:`github.io <.>`.
 The sources of Searx's documentation are located at :origin:`docs`.  Run
 :ref:`make docs-live <make docs-live>` to build HTML while editing.
 
-------
-
 .. sidebar:: Further reading
 
    - Sphinx-Primer_
@@ -36,8 +34,6 @@ The sources of Searx's documentation are located at :origin:`docs`.  Run
    :local:
    :backlinks: entry
 
-------
-
 Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is
 used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
 
@@ -593,6 +589,74 @@ Further list blocks
 - doctest blocks (:duref:`ref <doctest-blocks>`)
 
 
+Admonitions
+===========
+
+Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,
+:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.
+
+.. code:: reST
+
+   .. admonition:: generic admonition title
+
+      lorem ipsum ..
+
+   .. hint::
+
+      lorem ipsum ..
+
+   .. note::
+
+      lorem ipsum ..
+
+   .. warning::
+
+      lorem ipsum ..
+
+
+.. admonition:: generic admonition title
+
+   lorem ipsum ..
+
+.. hint::
+
+   lorem ipsum ..
+
+.. note::
+
+   lorem ipsum ..
+
+.. tip::
+
+   lorem ipsum ..
+
+.. attention::
+
+   lorem ipsum ..
+
+.. caution::
+
+   lorem ipsum ..
+
+.. danger::
+
+   lorem ipsum ..
+
+.. important::
+
+   lorem ipsum ..
+
+.. error::
+
+   lorem ipsum ..
+
+.. warning::
+
+   lorem ipsum ..
+
+
+
 .. _KISS: https://en.wikipedia.org/wiki/KISS_principle
 .. _readability: https://docs.python-guide.org/writing/style/
 .. _Sphinx-Primer:

{'commit': 'diff --git a/docs/_themes/searx/static/searx.css b/docs/_themes/searx/static/searx.css\nindex 747cb050..10cfc413 100644\n--- a/docs/_themes/searx/static/searx.css\n+++ b/docs/_themes/searx/static/searx.css\n@@ -28,53 +28,64 @@ p.sidebar-title, .sidebar p {\n   list-style-type: disclosure-closed;\n }\n \n+/* admonitions\n+*/\n \n-div.admonition,\n-div.topic {\n+div.admonition, div.topic {\n   background-color: #fafafa;\n   margin: 8px 0px;\n   padding: 1em;\n-  border: none;\n+  border-radius: 3pt 0 0 3pt;\n+  border-top: none;\n+  border-right: none;\n+  border-bottom: none;\n+  border-left: 5pt solid #ccc;\n+}\n+\n+p.admonition-title:after {\n+  content: none;\n+}\n+\n+.admonition.hint      { border-color: #416dc0b0; }\n+.admonition.note      { border-color: #6c856cb0; }\n+.admonition.tip       { border-color: #85c5c2b0; }\n+.admonition.attention { border-color: #ecec97b0; }\n+.admonition.caution   { border-color: #a6c677b0; }\n+.admonition.danger    { border-color: #d46262b0; }\n+.admonition.important { border-color: #dfa3a3b0; }\n+.admonition.error     { border-color: red; }\n+.admonition.warning   { border-color: darkred; }\n+\n+.admonition.admonition-generic-admonition-title {\n+    border-color: #416dc0b0;\n }\n \n+\n /* admonitions with (rendered) reST markup examples (:class: rst-example)\n  *\n  * .. admonition:: title of the example\n  *     :class: rst-example\n  *     ....\n-/* navigation menu: use sans font and select light/dark colors for better\n-* contrast.\n */\n \n div.rst-example {\n-    padding-left: 12px;\n-    padding-right: 12px;\n-    background-color: white;\n-    transform: scale(0.9);\n-    transition: transform 1s;\n+  padding-left: 12px;\n+  padding-right: 12px;\n+  background-color: inherit;\n+  transform: scale(0.9);\n+  transition: transform 1s;\n+  border-left: none;\n }\n \n-/* div.rst-example > .admonition-title { */\n-/*     background-color: inherit; */\n-/*     color: inherit; */\n-/* } */\n-\n-/* div.rst-example > .admonition-title:after{ */\n-/*     font-family: inherit; */\n-/*     font-style: italic; */\n-/*     content: "     // hover mouse over .."; */\n-/* } */\n-\n @media screen {\n-   div.rst-example:hover {\n-       transform: scale(1);\n-       background-color: inherit;\n-       padding-left: inherit;\n-       padding-right: inherit;\n-       border-left: inherit;\n-   }\n-\n-   div.rst-example:hover > .admonition-title {\n-       display: none;\n-   }\n+  div.rst-example:hover {\n+    transform: scale(1);\n+    padding-left: inherit;\n+    padding-right: inherit;\n+    border-left: inherit;\n+  }\n+\n+  div.rst-example:hover > .admonition-title {\n+    display: none;\n+  }\n }\ndiff --git a/docs/dev/reST.rst b/docs/dev/reST.rst\nindex 5522f9e1..69e4a930 100644\n--- a/docs/dev/reST.rst\n+++ b/docs/dev/reST.rst\n@@ -16,8 +16,6 @@ generated and deployed at :docs:`github.io <.>`.\n The sources of Searx\'s documentation are located at :origin:`docs`.  Run\n :ref:`make docs-live <make docs-live>` to build HTML while editing.\n \n-------\n-\n .. sidebar:: Further reading\n \n    - Sphinx-Primer_\n@@ -36,8 +34,6 @@ The sources of Searx\'s documentation are located at :origin:`docs`.  Run\n    :local:\n    :backlinks: entry\n \n-------\n-\n Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is\n used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.\n \n@@ -593,6 +589,74 @@ Further list blocks\n - doctest blocks (:duref:`ref <doctest-blocks>`)\n \n \n+Admonitions\n+===========\n+\n+Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,\n+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,\n+:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.\n+\n+.. code:: reST\n+\n+   .. admonition:: generic admonition title\n+\n+      lorem ipsum ..\n+\n+   .. hint::\n+\n+      lorem ipsum ..\n+\n+   .. note::\n+\n+      lorem ipsum ..\n+\n+   .. warning::\n+\n+      lorem ipsum ..\n+\n+\n+.. admonition:: generic admonition title\n+\n+   lorem ipsum ..\n+\n+.. hint::\n+\n+   lorem ipsum ..\n+\n+.. note::\n+\n+   lorem ipsum ..\n+\n+.. tip::\n+\n+   lorem ipsum ..\n+\n+.. attention::\n+\n+   lorem ipsum ..\n+\n+.. caution::\n+\n+   lorem ipsum ..\n+\n+.. danger::\n+\n+   lorem ipsum ..\n+\n+.. important::\n+\n+   lorem ipsum ..\n+\n+.. error::\n+\n+   lorem ipsum ..\n+\n+.. warning::\n+\n+   lorem ipsum ..\n+\n+\n+\n .. _KISS: https://en.wikipedia.org/wiki/KISS_principle\n .. _readability: https://docs.python-guide.org/writing/style/\n .. _Sphinx-Primer:\n', 'commit_subject': 'doc: reST primer -- describe admonitions & customize their CSS', 'repo_name': 'asciimoo/searx', 'committer': {'name': 'Markus Heiser', 'email': '14dfd67dd72e7ac80c040b62bb932f1e121795cc@darmarit.de', 'time_sec': '1576836101', 'tz_offset': '60', 'date': {'seconds': '1576836101'}}, 'commit_tree': 'e7dde5085527c62dd7b24968e6ebc34349eaa7f7', 'commit_message': 'doc: reST primer -- describe admonitions & customize their CSS\n\nSigned-off-by: Markus Heiser <14dfd67dd72e7ac80c040b62bb932f1e121795cc@darmarit.de>\n', 'language_name': 'HTML', 'license': 'agpl-3.0', 'hunks': "@@ -16,8 +16,6 @@ generated and deployed at :docs:`github.io <.>`.\n The sources of Searx's documentation are located at :origin:`docs`.  Run\n :ref:`make docs-live <make docs-live>` to build HTML while editing.\n \n-------\n-\n .. sidebar:: Further reading\n \n    - Sphinx-Primer_\n@@ -36,8 +34,6 @@ The sources of Searx's documentation are located at :origin:`docs`.  Run\n    :local:\n    :backlinks: entry\n \n-------\n-\n Sphinx_ and reST_ have their place in the python ecosystem.  Over that reST is\n used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.\n \n@@ -593,6 +589,74 @@ Further list blocks\n - doctest blocks (:duref:`ref <doctest-blocks>`)\n \n \n+Admonitions\n+===========\n+\n+Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,\n+:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, ,\n+:dudir:`warning` and the generic :dudir:`admonition <admonitions>`.\n+\n+.. code:: reST\n+\n+   .. admonition:: generic admonition title\n+\n+      lorem ipsum ..\n+\n+   .. hint::\n+\n+      lorem ipsum ..\n+\n+   .. note::\n+\n+      lorem ipsum ..\n+\n+   .. warning::\n+\n+      lorem ipsum ..\n+\n+\n+.. admonition:: generic admonition title\n+\n+   lorem ipsum ..\n+\n+.. hint::\n+\n+   lorem ipsum ..\n+\n+.. note::\n+\n+   lorem ipsum ..\n+\n+.. tip::\n+\n+   lorem ipsum ..\n+\n+.. attention::\n+\n+   lorem ipsum ..\n+\n+.. caution::\n+\n+   lorem ipsum ..\n+\n+.. danger::\n+\n+   lorem ipsum ..\n+\n+.. important::\n+\n+   lorem ipsum ..\n+\n+.. error::\n+\n+   lorem ipsum ..\n+\n+.. warning::\n+\n+   lorem ipsum ..\n+\n+\n+\n .. _KISS: https://en.wikipedia.org/wiki/KISS_principle\n .. _readability: https://docs.python-guide.org/writing/style/\n .. _Sphinx-Primer:\n", 'addition_count': 68, 'deletion_count': 4, 'src_file': 'a/docs/dev/reST.rst', 'tgt_file': 'b/docs/dev/reST.rst', 'file_extension': '.rst', 'before_file': '.. _reST primer:\n\n===========\nreST primer\n===========\n\n.. sidebar:: KISS_ and readability_\n\n   Instead of defining more and more roles, we at searx encourage our\n   contributors to follow principles like KISS_ and readability_.\n\nWe at searx are using reStructuredText (aka reST_) markup for all kind of\ndocumentation, with the builders from the Sphinx_ project a HTML output is\ngenerated and deployed at :docs:`github.io <.>`.  For build prerequisites read\n:ref:`docs build`.\nThe sources of Searx\'s documentation are located at :origin:`docs`.  Run\n:ref:`make docs-live <make docs-live>` to build HTML while editing.\n\n------\n\n.. sidebar:: Further reading\n\n   - Sphinx-Primer_\n\n   - Sphinx-Primer_\n   - `Sphinx markup constructs`_\n   - reST_, docutils_, `docutils FAQ`_\n   - Sphinx_, `sphinx-doc FAQ`_\n   - `sphinx config`_, doctree_\n   - `sphinx cross references`_\n   - linuxdoc_\n   - intersphinx_\n   - sphinx-jinja_\n   - `Sphinx\'s autodoc`_\n   - `Sphinx\'s Python domain`_, `Sphinx\'s C domain`_\n   :local:\n   :backlinks: entry\n\n------\n\nSphinx_ and reST_ have their place in the python ecosystem.  Over that reST is\nused in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.\n\n   :local:\n   :backlinks: entry\n\nSphinx_ and reST_ have their place in the python ecosystem.  Over that reST is\nused in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.\n\n.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html\n\n.. sidebar:: Content matters\n\n   The readability_ of the reST sources has its value, therefore we recommend to\n   make sparse usage of reST markup / .. content matters!\n\n**reST** is a plaintext markup language, its markup is *mostly* intuitive and\nyou will not need to learn much to produce well formed articles with.  I use the\nword *mostly*: like everything in live, reST has its advantages and\ndisadvantages, some markups feel a bit grumpy (especially if you are used to\nother plaintext markups).\n\nSoft skills\n===========\n\nBefore going any deeper into the markup let\'s face on some **soft skills** a\ntrained author brings with, to reach a well feedback from readers:\n\n- Documentation is dedicated to an audience and answers questions from the\n  audience point of view.\n- Don\'t detail things which are general knowledge from the audience point of\n  view.\n- Limit the subject, use cross links for any further reading.\n\nTo be more concrete what a *point of view* means.  In the (:origin:`docs`)\nfolder we have three sections (and the *blog* folder), each dedicate to a\ndifferent group of audience.\n\nUser\'s POV: :origin:`docs/user`\n  A typical user knows about search engines and might have heard about\n  meta crawlers and privacy.\n\nAdmin\'s POV: :origin:`docs/admin`\n  A typical Admin knows about setting up services on a linux system, but he does\n  not know all the pros and cons of a searx setup.\n\nDeveloper\'s POV: :origin:`docs/dev`\n  Depending on the readability_ of code, a typical developer is able to read and\n  understand source code.  Describe what a item aims to do (e.g. a function).\n  If the chronological order matters, describe it.  Name the *out-of-limits\n  conditions* and all the side effects a external developer will not know.\n\n.. _reST inline markup:\n\nBasic inline markup\n===================\n\n.. sidebar:: Inline markup\n\n   - :ref:`reST roles`\n   - :ref:`reST smart ref`\n\nBasic inline markup is done with asterisks and backquotes.  If asterisks or\nbackquotes appear in running text and could be confused with inline markup\ndelimiters, they have to be escaped with a backslash (``\\*pointer``).\n\n.. table:: basic inline markup\n   :widths: 4 3 7\n\n   ================================================ ==================== ========================\n   description                                      rendered             markup\n   ================================================ ==================== ========================\n   one asterisk for emphasis                        *italics*            ``*italics*``\n   two asterisks for strong emphasis                **boldface**         ``**boldface**``\n   backquotes for code samples and literals         ``foo()``            ````foo()````\n   quote asterisks or backquotes                    \\*foo is a pointer   ``\\*foo is a pointer``\n   ================================================ ==================== ========================\n\n.. _reST basic structure:\n\nBasic article structure\n=======================\n\nThe basic structure of an article makes use of heading adornments to markup\nchapter, sections and subsections.\n\n.. _reST template:\n\nreST template\n-------------\n\nreST template for an simple article:\n\n.. code:: reST\n\n    .. _doc refname:\n\n    ==============\n    Document title\n    ==============\n\n    Lorem ipsum dolor sit amet, consectetur adipisici elit ..  Further read\n    :ref:`chapter refname`.\n\n    .. _chapter refname:\n\n    Chapter\n    =======\n\n    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut\n    aliquid ex ea commodi consequat ...\n\n    .. _section refname:\n\n    Section\n    -------\n\n    lorem ..\n\n    .. _subsection refname:\n\n    Subsection\n    ~~~~~~~~~~\n\n    lorem ..\n\n\nHeadings\n--------\n\n#. title - with overline for document title:\n\n  .. code:: reST\n\n    ==============\n    Document title\n    ==============\n\n\n#. chapter - with anchor named ``anchor name``:\n\n   .. code:: reST\n\n      .. _anchor name:\n\n      Chapter\n      =======\n\n#. section\n\n   .. code:: reST\n\n      Section\n      -------\n\n#. subsection\n\n   .. code:: reST\n\n      Subsection\n      ~~~~~~~~~~\n\n\n\nAnchors & Links\n===============\n\n.. _reST anchor:\n\nAnchors\n-------\n\n.. _ref role:\n   https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref\n\nTo refer a point in the documentation a anchor is needed.  The :ref:`reST\ntemplate <reST template>` shows an example where a chapter titled *"Chapters"*\ngets an anchor named ``chapter title``.  Another example from *this* document,\nwhere the anchor named ``reST anchor``:\n\n.. code:: reST\n\n   .. _reST anchor:\n\n   Anchors\n   -------\n\n   To refer a point in the documentation a anchor is needed ...\n\nTo refer anchors use the `ref role`_ markup:\n\n.. code:: reST\n\n   Visit chapter :ref:`reST anchor`.  Or set hyperlink text manually :ref:`foo\n   bar <reST anchor>`.\n\n.. admonition:: ``:ref:`` role\n   :class: rst-example\n\n   Visist chapter :ref:`reST anchor`.  Or set hyperlink text manually :ref:`foo\n   bar <reST anchor>`.\n\n.. _reST ordinary ref:\n\nLink ordinary URL\n-----------------\n\nIf you need to reference external URLs use *named* hyperlinks to maintain\nreadability of reST sources.  Here is a example taken from *this* article:\n\n.. code:: reST\n\n   .. _Sphinx Field Lists:\n      https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html\n\n   With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more\n   readable.\n\n   And this shows the alternative (less readable) hyperlink markup `Sphinx Field\n   Lists\n   <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.\n\n.. admonition:: Named hyperlink\n   :class: rst-example\n\n   With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more\n   readable.\n\n   And this shows the alternative (less readable) hyperlink markup `Sphinx Field\n   Lists\n   <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.\n\n\n.. _reST smart ref:\n\nSmart refs\n----------\n\nWith the power of sphinx.ext.extlinks_ and intersphinx_ referencing external\ncontent becomes smart.\n\n.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_\n   :widths: 4 3 7\n\n   ========================== ================================== ====================================\n   refer ...                  rendered example                   markup\n   ========================== ================================== ====================================\n   :rst:role:`rfc`            :rfc:`822`                         ``:rfc:`822```\n   :rst:role:`pep`            :pep:`8`                           ``:pep:`8```\n   sphinx.ext.extlinks_\n   --------------------------------------------------------------------------------------------------\n   project\'s wiki article     :wiki:`Offline-engines`            ``:wiki:`Offline-engines```\n   to docs public URL         :docs:`dev/reST.html`              ``:docs:`dev/reST.html```\n   files & folders origin     :origin:`docs/dev/reST.rst`        ``:origin:`docs/dev/reST.rst```\n   pull request               :pull:`1756`                       ``:pull:`1756```\n   patch                      :patch:`af2cae6`                   ``:patch:`af2cae6```\n   PyPi package               :pypi:`searx`                      ``:pypi:`searx```\n   manual page man            :man:`bash`                        ``:man:`bash```\n   intersphinx_\n   --------------------------------------------------------------------------------------------------\n   external anchor            :ref:`python:and`                  ``:ref:`python:and```\n   external doc anchor        :doc:`jinja:templates`             ``:doc:`jinja:templates```\n   python code object         :py:obj:`datetime.datetime`        ``:py:obj:`datetime.datetime```\n   flask code object          :py:obj:`flask.Flask`              ``:py:obj:`flask.Flask```\n   ========================== ================================== ====================================\n\n\nIntersphinx is configured in :origin:`docs/conf.py`:\n\n.. code:: python\n\n    intersphinx_mapping = {\n        "python": ("https://docs.python.org/3/", None),\n        "flask": ("https://flask.palletsprojects.com/", None),\n        "jinja": ("https://jinja.palletsprojects.com/", None),\n        "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),\n        "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),\n    }\n\n\nTo list all anchors of the inventory (e.g. ``python``) use:\n\n.. code:: sh\n\n   $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv\n   ...\n   $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv\n   ...\n\nLiteral blocks\n==============\n\nThe simplest form of :duref:`literal-blocks` is a indented block introduced by\ntwo colons (``::``).  For highlighting use :dudir:`highlight` or :ref:`reST\ncode` directive.  To include literals from external files use\n:rst:dir:`literalinclude` or :ref:`kernel-include <kernel-include-directive>`\ndirective (latter one expands environment variables in the path name).\n\n.. _reST literal:\n\n``::``\n------\n\n.. code:: reST\n\n   ::\n\n     Literal block\n\n   Lorem ipsum dolor::\n\n     Literal block\n\n   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy\n   eirmod tempor invidunt ut labore ::\n\n     Literal block\n\n.. admonition:: Literal block\n   :class: rst-example\n\n   ::\n\n     Literal block\n\n   Lorem ipsum dolor::\n\n     Literal block\n\n   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy\n   eirmod tempor invidunt ut labore ::\n\n     Literal block\n\n\n.. _reST code:\n\n``code-block``\n--------------\n\n.. _pygments: https://pygments.org/languages/\n\n.. sidebar:: Syntax highlighting\n\n   is handled by pygments_.\n\nThe :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive\nwith additional options.  To learn more about code literals visit\n:ref:`sphinx:code-examples`.\n\n.. code-block:: reST\n\n   The URL ``/stats`` handle is shown in :ref:`stats-handle`\n\n   .. code-block:: Python\n      :caption: python code block\n      :name: stats-handle\n\n      @app.route(\'/stats\', methods=[\'GET\'])\n      def stats():\n          """Render engine statistics page."""\n          stats = get_engines_stats()\n          return render(\n              \'stats.html\'\n              , stats = stats )\n\n.. code-block:: reST\n\n.. admonition:: Code block\n   :class: rst-example\n\n   The URL ``/stats`` handle is shown in :ref:`stats-handle`\n\n   .. code-block:: Python\n      :caption: python code block\n      :name: stats-handle\n\n      @app.route(\'/stats\', methods=[\'GET\'])\n      def stats():\n          """Render engine statistics page."""\n          stats = get_engines_stats()\n          return render(\n              \'stats.html\'\n              , stats = stats )\n\nUnicode substitution\n====================\n\nThe :dudir:`unicode directive <unicode-character-codes>` converts Unicode\ncharacter codes (numerical values) to characters.  This directive can only be\nused within a substitution definition.\n\n.. code-block:: reST\n\n   .. |copy| unicode:: 0xA9 .. copyright sign\n   .. |(TM)| unicode:: U+2122\n\n   Trademark |(TM)| and copyright |copy| glyphs.\n\n.. admonition:: Unicode\n   :class: rst-example\n\n   .. |copy| unicode:: 0xA9 .. copyright sign\n   .. |(TM)| unicode:: U+2122\n\n   Trademark |(TM)| and copyright |copy| glyphs.\n\n\n.. _reST roles:\n\nRoles\n=====\n\n.. sidebar:: Further reading\n\n   - `Sphinx Roles`_\n   - :doc:`sphinx:usage/restructuredtext/domains`\n\n\nA *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of\nexplicit markup.  It signifies that that the enclosed text should be interpreted\nin a specific way.\n\nThe general markup is one of:\n\n.. code:: reST\n\n   :rolename:`ref-name`\n   :rolename:`ref text <ref-name>`\n\n.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_\n   :widths: 4 3 7\n\n   ========================== ================================== ====================================\n   role                       rendered example                   markup\n   ========================== ================================== ====================================\n   :rst:role:`guilabel`       :guilabel:`&Cancel`                ``:guilabel:`&Cancel```\n   :rst:role:`kbd`            :kbd:`C-x C-f`                     ``:kbd:`C-x C-f```\n   :rst:role:`menuselection`  :menuselection:`Open --> File`     ``:menuselection:`Open --> File```\n   :rst:role:`download`       :download:`this file <reST.rst>`   ``:download:`this file <reST.rst>```\n   math_                      :math:`a^2 + b^2 = c^2`            ``:math:`a^2 + b^2 = c^2```\n   :rst:role:`ref`            :ref:`svg image example`           ``:ref:`svg image example```\n   :rst:role:`command`        :command:`ls -la`                  ``:command:`ls -la```\n   :durole:`emphasis`         :emphasis:`italic`                 ``:emphasis:`italic```\n   :durole:`strong`           :strong:`bold`                     ``:strong:`bold```\n   :durole:`literal`          :literal:`foo()`                   ``:literal:`foo()```\n   :durole:`subscript`        H\\ :sub:`2`\\ O                     ``H\\ :sub:`2`\\ O``\n   :durole:`superscript`      E = mc\\ :sup:`2`                   ``E = mc\\ :sup:`2```\n   :durole:`title-reference`  :title:`Time`                      ``:title:`Time```\n   ========================== ================================== ====================================\n\nFigures & Images\n================\n\n.. sidebar:: Image processing\n\n   With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process\n   is flexible.  To get best results in the generated output format, install\n   ImageMagick_ and Graphviz_.\n\nSearx\'s sphinx setup includes: :ref:`linuxdoc:kfigure`.  Scalable here means;\nscalable in sense of the build process.  Normally in absence of a converter\ntool, the build process will break.  From the authors POV it’s annoying to care\nabout the build process when handling with images, especially since he has no\naccess to the build process.  With :ref:`linuxdoc:kfigure` the build process\ncontinues and scales output quality in dependence of installed image processors.\n\nIf you want to add an image, you should use the ``kernel-figure`` (inheritance\nof :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)\ndirectives.  E.g. to insert a figure with a scalable image format use SVG\n(:ref:`svg image example`):\n\n.. code:: reST\n\n   .. _svg image example:\n\n   .. kernel-figure:: svg_image.svg\n      :alt: SVG image example\n\n      Simple SVG image\n\n    To refer the figure, a caption block is needed: :ref:`svg image example`.\n\n.. _svg image example:\n\n.. kernel-figure:: svg_image.svg\n   :alt: SVG image example\n\n   Simple SVG image.\n\nTo refer the figure, a caption block is needed: :ref:`svg image example`.\n\nDOT files (aka Graphviz)\n------------------------\n\nWith :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is\ngiven.\n\n- `Graphviz\'s dot`_\n- DOT_\n- Graphviz_\n\nA simple example is shown in :ref:`dot file example`:\n\n.. code:: reST\n\n   .. _dot file example:\n\n   .. kernel-figure:: hello.dot\n      :alt: hello world\n\n      DOT\'s hello world example\n\n.. admonition:: hello.dot\n   :class: rst-example\n\n   .. _dot file example:\n\n   .. kernel-figure:: hello.dot\n      :alt: hello world\n\n      DOT\'s hello world example\n\n``kernel-render`` DOT\n---------------------\n\nEmbed *render* markups (or languages) like Graphviz\'s **DOT** is provided by the\n:ref:`linuxdoc:kernel-render` directive.  A simple example of embedded DOT_ is\nshown in figure :ref:`dot render example`:\n\n.. code:: reST\n\n   .. _dot render example:\n\n   .. kernel-render:: DOT\n      :alt: digraph\n      :caption: Embedded  DOT (Graphviz) code\n\n      digraph foo {\n        "bar" -> "baz";\n      }\n\n   Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot\n   render example`.\n\nPlease note :ref:`build tools <linuxdoc:kfigure_build_tools>`.  If Graphviz_ is\ninstalled, you will see an vector image.  If not, the raw markup is inserted as\n*literal-block*.\n\n.. admonition:: kernel-render DOT\n   :class: rst-example\n\n- doctest blocks (:duref:`ref <doctest-blocks>`)\n\n\n.. _KISS: https://en.wikipedia.org/wiki/KISS_principle\n.. _readability: https://docs.python-guide.org/writing/style/\n.. _Sphinx-Primer:\nBullet list\n-----------\n\nList markup (:duref:`ref <bullet-lists>`) is simple:\n\n.. code:: reST\n\n   - This is a bulleted list.\n\n     1. Nested lists are possible, but be aware that they must be separated from\n        the parent list items by blank line\n     2. Second item of nested list\n\n   - It has two items, the second\n     item uses two lines.\n\n   #. This is a numbered list.\n   #. It has two items too.\n\n.. admonition:: bullet list\n   :class: rst-example\n\n   - This is a bulleted list.\n\n     1. Nested lists are possible, but be aware that they must be separated from\n        the parent list items by blank line\n     2. Second item of nested list\n\n   - It has two items, the second\n     item uses two lines.\n\n   #. This is a numbered list.\n   #. It has two items too.\n\n\nHorizontal list\n---------------\n\nThe :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact\nlist.\n\n.. code:: reST\n\n   .. hlist::\n\n      - first list item\n      - second list item\n      - third list item\n      ...\n\n.. admonition:: hlist\n   :class: rst-example\n\n   .. hlist::\n\n      - first list item\n      - second list item\n      - third list item\n      - next list item\n      - next list item xxxx\n      - next list item yyyy\n      - next list item zzzz\n\n\nDefinition list\n---------------\n\n.. sidebar:: Note ..\n\n   - the term cannot have more than one line of text\n\n   - there is **no blank line between term and definition block** // this\n     distinguishes definition lists (:duref:`ref <definition-lists>`) from block\n     quotes (:duref:`ref <block-quotes>`).\n\nEach definition list (:duref:`ref <definition-lists>`) item contains a term,\noptional classifiers and a definition.  A term is a simple one-line word or\nphrase.  Optional classifiers may follow the term on the same line, each after\nan inline \' : \' (**space, colon, space**).  A definition is a block indented\nrelative to the term, and may contain multiple paragraphs and other body\nelements.  There may be no blank line between a term line and a definition block\n(*this distinguishes definition lists from block quotes*).  Blank lines are\nrequired before the first and after the last definition list item, but are\noptional in-between.\n\nDefinition lists are created as follows:\n\n.. code:: reST\n\n   term 1 (up to a line of text)\n       Definition 1.\n\n   See the typo : this line is not a term!\n\n     And this is not term\'s definition.  **There is a blank line** in between\n     the line above and this paragraph.  That\'s why this paragraph is taken as\n     **block quote** (:duref:`ref <block-quotes>`) and not as term\'s definition!\n\n   term 2\n       Definition 2, paragraph 1.\n\n       Definition 2, paragraph 2.\n\n   term 3 : classifier\n       Definition 3.\n\n   term 4 : classifier one : classifier two\n       Definition 4.\n\n.. admonition:: definition list\n   :class: rst-example\n\n   term 1 (up to a line of text)\n       Definition 1.\n\n   See the typo : this line is not a term!\n\n     And this is not term\'s definition.  **There is a blank line** in between\n     the line above and this paragraph.  That\'s why this paragraph is taken as\n     **block quote** (:duref:`ref <block-quotes>`) and not as term\'s definition!\n\n\n   term 2\n       Definition 2, paragraph 1.\n\n       Definition 2, paragraph 2.\n\n   term 3 : classifier\n       Definition 3.\n\n   term 4 : classifier one : classifier two\n\n\nQuoted paragraphs\n-----------------\n\nQuoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting\nthem more than the surrounding paragraphs.  Line blocks (:duref:`ref\n<line-blocks>`) are a way of preserving line breaks:\n\n.. code:: reST\n\n   normal paragraph ...\n   lorem ipsum.\n\n      Quoted paragraph ...\n      lorem ipsum.\n\n   | These lines are\n   | broken exactly like in\n   | the source file.\n\n\n.. admonition:: Quoted paragraph and line block\n   :class: rst-example\n\n   normal paragraph ...\n   lorem ipsum.\n\n      Quoted paragraph ...\n      lorem ipsum.\n\n   | These lines are\n   | broken exactly like in\n   | the source file.\n\n\n.. _reST field list:\n\nField Lists\n-----------\n\n.. _Sphinx Field Lists:\n   https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html\n\n.. sidebar::  bibliographic fields\n\n   First lines fields are bibliographic fields, see `Sphinx Field Lists`_.\n\nField lists are used as part of an extension syntax, such as options for\ndirectives, or database-like records meant for further processing.  Field lists\nare mappings from field names to field bodies.  They marked up like this:\n\n.. code:: reST\n\n   :fieldname: Field content\n   :foo:       first paragraph in field foo\n\n               second paragraph in field foo\n\n   :bar:       Field content\n\n.. admonition:: Field List\n   :class: rst-example\n\n   :fieldname: Field content\n   :foo:       first paragraph in field foo\n\n               second paragraph in field foo\n\n   :bar:       Field content\n\n\nThey are commonly used in Python documentation:\n\n.. code:: python\n\n   def my_function(my_arg, my_other_arg):\n       """A function just for me.\n\n       :param my_arg: The first of my arguments.\n       :param my_other_arg: The second of my arguments.\n\n       :returns: A message (just for me, of course).\n       """\n\nFurther list blocks\n-------------------\n\n- field lists (:duref:`ref <field-lists>`, with caveats noted in\n  :ref:`reST field list`)\n- option lists (:duref:`ref <option-lists>`)\n- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)\n- doctest blocks (:duref:`ref <doctest-blocks>`)\n\n\nAdmonitions\n===========\n\nSidebar\n-------\n\nSidebar is an eye catcher, often used for admonitions pointing further stuff or\nsite effects.  Here is the source of the sidebar :ref:`on top of this page <reST\nprimer>`.\n\n.. code:: reST\n\n   .. sidebar:: KISS_ and readability_\n\n      Instead of defining more and more roles, we at searx encourage our\n      contributors to follow principles like KISS_ and readability_.\n\nGeneric admonition\n------------------\n\nThe generic :dudir:`admonition <admonitions>` needs a title:\n\n.. code:: reST\n\n   .. admonition:: generic admonition title\n\n      lorem ipsum ..\n\n\n.. admonition:: generic admonition title\n\n   lorem ipsum ..\n\n\nSpecific admonitions\n--------------------\n\nSpecific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,\n:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and\n:dudir:`warning` .\n\n.. code:: reST\n\n   .. hint::\n\n      lorem ipsum ..\n\n   .. note::\n\n      lorem ipsum ..\n\n   .. warning::\n\n      lorem ipsum ..\n\n\n.. hint::\n\n   lorem ipsum ..\n\n.. note::\n\n   lorem ipsum ..\n\n.. tip::\n\n   lorem ipsum ..\n\n.. attention::\n\n   lorem ipsum ..\n\n.. caution::\n\n   lorem ipsum ..\n\n.. danger::\n\n   lorem ipsum ..\n\n.. important::\n\n   lorem ipsum ..\n\n.. error::\n\n   lorem ipsum ..\n\n.. warning::\n\n   lorem ipsum ..\n\n\nTables\n======\n\n.. sidebar:: Nested tables\n\n   Nested tables are ugly! Not all builder support nested tables, don\'t use\n   them!\n\nASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might\nbe comfortable for readers of the text-files, but they have huge disadvantages\nin the creation and modifying.  First, they are hard to edit.  Think about\nadding a row or a column to a ASCII-art table or adding a paragraph in a cell,\nit is a nightmare on big tables.\n\n\n.. sidebar:: List tables\n\n   For meaningful patch and diff use :ref:`reST flat table`.\n\nSecond the diff of modifying ASCII-art tables is not meaningful, e.g. widening a\ncell generates a diff in which also changes are included, which are only\nascribable to the ASCII-art.  Anyway, if you prefer ASCII-art for any reason,\nhere are some helpers:\n\n* `Emacs Table Mode`_\n* `Online Tables Generator`_\n\n.. _reST simple table:\n\nSimple tables\n-------------\n\n:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*.  If\nyour table need some metadata (e.g. a title) you need to add the ``.. table::\ndirective`` :dudir:`(ref) <table>` in front and place the table in its body:\n\n.. code:: reST\n\n   .. table:: foo gate truth table\n      :widths: grid\n      :align: left\n\n      ====== ====== ======\n          Inputs    Output\n      ------------- ------\n      A      B      A or B\n      ====== ====== ======\n      False\n      --------------------\n      True\n      --------------------\n      True   False  True\n             (foo)\n      ------ ------ ------\n      False  True\n             (foo)\n      ====== =============\n\n.. admonition:: Simple ASCII table\n   :class: rst-example\n\n   .. table:: foo gate truth table\n      :widths: grid\n      :align: left\n\n      ====== ====== ======\n          Inputs    Output\n      ------------- ------\n      A      B      A or B\n      ====== ====== ======\n      False\n      --------------------\n      True\n      --------------------\n      True   False  True\n             (foo)\n      ------ ------ ------\n      False  True\n             (foo)\n      ====== =============\n\n\n\n.. _reST grid table:\n\nGrid tables\n-----------\n\n:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:\n\n.. code:: reST\n\n   .. table:: grid table example\n      :widths: 1 1 5\n\n      +------------+------------+-----------+\n      | Header 1   | Header 2   | Header 3  |\n      +============+============+===========+\n      | body row 1 | column 2   | column 3  |\n      +------------+------------+-----------+\n      | body row 2 | Cells may span columns.|\n      +------------+------------+-----------+\n      | body row 3 | Cells may  | - Cells   |\n      +------------+ span rows. | - contain |\n      | body row 4 |            | - blocks. |\n      +------------+------------+-----------+\n\n.. admonition:: ASCII grid table\n   :class: rst-example\n\n   .. table:: grid table example\n      :widths: 1 1 5\n\n      +------------+------------+-----------+\n      | Header 1   | Header 2   | Header 3  |\n      +============+============+===========+\n      | body row 1 | column 2   | column 3  |\n      +------------+------------+-----------+\n      | body row 2 | Cells may span columns.|\n      +------------+------------+-----------+\n      | body row 3 | Cells may  | - Cells   |\n      +------------+ span rows. | - contain |\n      | body row 4 |            | - blocks. |\n      +------------+------------+-----------+\n\n\n.. _reST flat table:\n\nflat-table\n----------\n\nThe ``flat-table`` is a further developed variant of the :ref:`list tables\n<linuxdoc:list-table-directives>`.  It is a double-stage list similar to the\n:dudir:`list-table` with some additional features:\n\ncolumn-span: ``cspan``\n  with the role ``cspan`` a cell can be extended through additional columns\n\nrow-span: ``rspan``\n  with the role ``rspan`` a cell can be extended through additional rows\n\nauto-span:\n  spans rightmost cell of a table row over the missing cells on the right side\n  of that table-row.  With Option ``:fill-cells:`` this behavior can changed\n  from *auto span* to *auto fill*, which automatically inserts (empty) cells\n  instead of spanning the last cell.\n\noptions:\n  :header-rows:   [int] count of header rows\n  :stub-columns:  [int] count of stub columns\n  :widths:        [[int] [int] ... ] widths of columns\n  :fill-cells:    instead of auto-span missing cells, insert missing cells\n\nroles:\n  :cspan: [int] additional columns (*morecols*)\n  :rspan: [int] additional rows (*morerows*)\n\nThe example below shows how to use this markup.  The first level of the staged\nlist is the *table-row*. In the *table-row* there is only one markup allowed,\nthe list of the cells in this *table-row*. Exception are *comments* ( ``..`` )\nand *targets* (e.g. a ref to :ref:`row 2 of table\'s body <row body 2>`).\n\n.. code:: reST\n\n   .. flat-table:: ``flat-table`` example\n      :header-rows: 2\n      :stub-columns: 1\n      :widths: 1 1 1 1 2\n\n      * - :rspan:`1` head / stub\n        - :cspan:`3` head 1.1-4\n\n      * - head 2.1\n        - head 2.2\n        - head 2.3\n        - head 2.4\n\n      * .. row body 1 / this is a comment\n\n        - row 1\n        - :rspan:`2` cell 1-3.1\n        - cell 1.2\n        - cell 1.3\n        - cell 1.4\n\n      * .. Comments and targets are allowed on *table-row* stage.\n        .. _`row body 2`:\n\n        - row 2\n        - cell 2.2\n        - :rspan:`1` :cspan:`1`\n          cell 2.3 with a span over\n\n          * col 3-4 &\n          * row 2-3\n\n      * - row 3\n        - cell 3.2\n\n      * - row 4\n        - cell 4.1\n        - cell 4.2\n        - cell 4.3\n        - cell 4.4\n\n      * - row 5\n        - cell 5.1 with automatic span to right end\n\n      * - row 6\n        - cell 6.1\n        - ..\n\n\n.. admonition:: List table\n   :class: rst-example\n\n   .. flat-table:: ``flat-table`` example\n      :header-rows: 2\n      :stub-columns: 1\n      :widths: 1 1 1 1 2\n\n      * - :rspan:`1` head / stub\n        - :cspan:`3` head 1.1-4\n\n      * - head 2.1\n        - head 2.2\n        - head 2.3\n        - head 2.4\n\n      * .. row body 1 / this is a comment\n\n        - row 1\n        - :rspan:`2` cell 1-3.1\n        - cell 1.2\n        - cell 1.3\n        - cell 1.4\n\n      * .. Comments and targets are allowed on *table-row* stage.\n        .. _`row body 2`:\n\n        - row 2\n        - cell 2.2\n        - :rspan:`1` :cspan:`1`\n          cell 2.3 with a span over\n\n          * col 3-4 &\n          * row 2-3\n\n      * - row 3\n        - cell 3.2\n\n      * - row 4\n        - cell 4.1\n        - cell 4.2\n        - cell 4.3\n        - cell 4.4\n\n      * - row 5\n        - cell 5.1 with automatic span to right end\n\n      * - row 6\n        - cell 6.1\n        - ..\n\n\nCSV table\n---------\n\nCSV table might be the choice if you want to include CSV-data from a outstanding\n(build) process into your documentation.\n\n.. code:: reST\n\n   .. csv-table:: CSV table example\n      :header: .. , Column 1, Column 2\n      :widths: 2 5 5\n      :stub-columns: 1\n      :file: csv_table.txt\n\nContent of file ``csv_table.txt``:\n\n.. literalinclude:: csv_table.txt\n\n.. admonition:: CSV table\n   :class: rst-example\n\n   .. csv-table:: CSV table example\n      :header: .. , Column 1, Column 2\n      :widths: 3 5 5\n      :stub-columns: 1\n      :file: csv_table.txt\n\nTemplating\n==========\n\n.. sidebar:: Build environment\n\n   All *generic-doc* tasks are running in the :ref:`make install`.\n\nTemplating is suitable for documentation which is created generic at the build\ntime.  The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`make\ninstall` (with searx modules installed).  We use this e.g. to build chapter:\n:ref:`engines generic`.  Below the jinja directive from the\n:origin:`docs/admin/engines.rst` is shown:\n\n.. literalinclude:: ../admin/engines.rst\n   :language: reST\n   :start-after: .. _configured engines:\n\nThe context for the template is selected in the line ``.. jinja:: searx``.  In\nsphinx\'s build configuration (:origin:`docs/conf.py`) the ``searx`` context\ncontains the ``engines`` and ``plugins``.\n\n.. code:: py\n\n   import searx.search\n   import searx.engines\n   import searx.plugins\n   searx.search.initialize()\n   jinja_contexts = {\n      \'searx\': {\n         \'engines\': searx.engines.engines,\n         \'plugins\': searx.plugins.plugins\n      },\n   }\n\n\nTabbed views\n============\n\n.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs\n.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs\n.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs\n.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs\n\nWith `sphinx-tabs`_ extension we have *tabbed views*.  To provide installation\ninstructions with one tab per distribution we use the `group-tabs`_ directive,\nothers are basic-tabs_ and code-tabs_.  Below a *group-tab* example from\n:ref:`docs build` is shown:\n\n.. literalinclude:: ../admin/buildhosts.rst\n   :language: reST\n   :start-after: .. SNIP sh lint requirements\n   :end-before: .. SNAP sh lint requirements\n\n.. _math:\n\nMath equations\n==============\n\n.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics\n.. _amsmath user guide:\n   http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf\n\n.. sidebar:: About LaTeX\n\n   - `amsmath user guide`_\n   - Mathematics_\n   - :ref:`docs build`\n\nThe input language for mathematics is LaTeX markup using the :ctan:`amsmath`\npackage.\n\nTo embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for\ninline and directive :rst:dir:`.. math:: <math>` for block markup.\n\n.. code:: reST\n\n   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation\n   is shown.\n\n   .. math::\n      :label: schroedinger general\n\n       \\mathrm{i}\\hbar\\dfrac{\\partial}{\\partial t} |\\,\\psi (t) \\rangle =\n             \\hat{H} |\\,\\psi (t) \\rangle.\n\n.. admonition:: LaTeX math equation\n   :class: rst-example\n\n   In :math:numref:`schroedinger general` the time-dependent Schrödinger equation\n   is shown.\n\n   .. math::\n      :label: schroedinger general\n\n       \\mathrm{i}\\hbar\\dfrac{\\partial}{\\partial t} |\\,\\psi (t) \\rangle =\n             \\hat{H} |\\,\\psi (t) \\rangle.\n\n\nThe next example shows the difference of ``\\tfrac`` (*textstyle*) and ``\\dfrac``\n(*displaystyle*) used in a inline markup or another fraction.\n\n.. code:: reST\n\n   ``\\tfrac`` **inline example** :math:`\\tfrac{\\tfrac{1}{x}+\\tfrac{1}{y}}{y-z}`\n   ``\\dfrac`` **inline example** :math:`\\dfrac{\\dfrac{1}{x}+\\dfrac{1}{y}}{y-z}`\n\n.. admonition:: Line spacing\n   :class: rst-example\n\n   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy\n   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam\n   voluptua.  ...\n   ``\\tfrac`` **inline example** :math:`\\tfrac{\\tfrac{1}{x}+\\tfrac{1}{y}}{y-z}`\n   At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd\n   gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.\n\n   Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy\n   eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam\n   voluptua.  ...\n   ``\\tfrac`` **inline example** :math:`\\dfrac{\\dfrac{1}{x}+\\dfrac{1}{y}}{y-z}`\n   At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd\n   gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.\n\n\n.. _KISS: https://en.wikipedia.org/wiki/KISS_principle\n\n.. _readability: https://docs.python-guide.org/writing/style/\n.. _Sphinx-Primer:\n    https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\n.. _reST: https://docutils.sourceforge.io/rst.html\n.. _Sphinx Roles:\n    https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html\n.. _Sphinx: https://www.sphinx-doc.org\n.. _`sphinx-doc FAQ`: https://www.sphinx-doc.org/en/stable/faq.html\n.. _Sphinx markup constructs:\n    https://www.sphinx-doc.org/en/stable/markup/index.html\n.. _`sphinx cross references`:\n    https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations\n.. _sphinx.ext.extlinks:\n    https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html\n.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html\n.. _sphinx config: https://www.sphinx-doc.org/en/stable/config.html\n.. _Sphinx\'s autodoc: https://www.sphinx-doc.org/en/stable/ext/autodoc.html\n.. _Sphinx\'s Python domain:\n    https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain\n.. _Sphinx\'s C domain:\n   https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs\n.. _doctree:\n    https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases\n.. _docutils: http://docutils.sourceforge.net/docs/index.html\n.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html\n.. _linuxdoc: https://return42.github.io/linuxdoc\n.. _jinja: https://jinja.palletsprojects.com/\n.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja\n.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html\n.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html\n.. _`Graphviz\'s dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf\n.. _Graphviz: https://graphviz.gitlab.io\n.. _ImageMagick: https://www.imagemagick.org\n\n.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode\n.. _`Online Tables Generator`: https://www.tablesgenerator.com/text_tables\n.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html\n', 'message': 'doc: reST primer -- describe admonitions & customize their CSS\n\nSigned-off-by: Markus Heiser <14dfd67dd72e7ac80c040b62bb932f1e121795cc@darmarit.de>\n', 'author_name': 'Markus Heiser', 'lang': 'rst'}