git.iko.soy/searx
on 3bb97fc help sign in
searx/docs/dev/reST.rst
1428 lines 39 kB history raw
1.. _reST primer:
3===========
4reST primer
5===========
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_.
12We at searx are using reStructuredText (aka reST_) markup for all kind of
13documentation, with the builders from the Sphinx_ project a HTML output is
14generated and deployed at :docs:`github.io <.>`. For build prerequisites read
15:ref:`docs build`.
17The source files of Searx's documentation are located at :origin:`docs`. Sphinx
18assumes 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
23 - Sphinx-Primer_
24 - `Sphinx markup constructs`_
25 - reST_, docutils_, `docutils FAQ`_
26 - Sphinx_, `sphinx-doc FAQ`_
27 - `sphinx config`_, doctree_
28 - `sphinx cross references`_
29 - linuxdoc_
30 - intersphinx_
31 - sphinx-jinja_
32 - `Sphinx's autodoc`_
33 - `Sphinx's Python domain`_, `Sphinx's C domain`_
34 - SVG_, ImageMagick_
35 - DOT_, `Graphviz's dot`_, Graphviz_
38.. contents:: Contents
39 :depth: 3
40 :local:
41 :backlinks: entry
43Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is
44used 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
54you will not need to learn much to produce well formed articles with. I use the
55word *mostly*: like everything in live, reST has its advantages and
56disadvantages, some markups feel a bit grumpy (especially if you are used to
57other plaintext markups).
59Soft skills
60===========
62Before going any deeper into the markup let's face on some **soft skills** a
63trained 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
68 view.
69- Limit the subject, use cross links for any further reading.
71To be more concrete what a *point of view* means. In the (:origin:`docs`)
72folder we have three sections (and the *blog* folder), each dedicate to a
73different group of audience.
75User's POV: :origin:`docs/user`
76 A typical user knows about search engines and might have heard about
77 meta crawlers and privacy.
79Admin'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.
83Developer'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:
91Basic inline markup
92===================
94.. sidebar:: Inline markup
96 - :ref:`reST roles`
97 - :ref:`reST smart ref`
99Basic inline markup is done with asterisks and backquotes. If asterisks or
100backquotes appear in running text and could be confused with inline markup
101delimiters, they have to be escaped with a backslash (``\*pointer``).
103.. table:: basic inline markup
104 :widths: 4 3 7
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:
117Basic article structure
118=======================
120The basic structure of an article makes use of heading adornments to markup
121chapter, sections and subsections.
123.. _reST template:
125reST template
126-------------
128reST template for an simple article:
130.. code:: reST
132 .. _doc refname:
134 ==============
135 Document title
136 ==============
138 Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
139 :ref:`chapter refname`.
141 .. _chapter refname:
143 Chapter
144 =======
146 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
147 aliquid ex ea commodi consequat ...
149 .. _section refname:
151 Section
152 -------
154 lorem ..
156 .. _subsection refname:
158 Subsection
159 ~~~~~~~~~~
161 lorem ..
164Headings
165--------
167#. title - with overline for document title:
169 .. code:: reST
171 ==============
172 Document title
173 ==============
176#. chapter - with anchor named ``anchor name``:
178 .. code:: reST
180 .. _anchor name:
182 Chapter
183 =======
185#. section
187 .. code:: reST
189 Section
190 -------
192#. subsection
194 .. code:: reST
196 Subsection
197 ~~~~~~~~~~
201Anchors & Links
202===============
204.. _reST anchor:
206Anchors
207-------
209.. _ref role:
210 https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
212To refer a point in the documentation a anchor is needed. The :ref:`reST
213template <reST template>` shows an example where a chapter titled *"Chapters"*
214gets an anchor named ``chapter title``. Another example from *this* document,
215where the anchor named ``reST anchor``:
217.. code:: reST
219 .. _reST anchor:
221 Anchors
222 -------
224 To refer a point in the documentation a anchor is needed ...
226To refer anchors use the `ref role`_ markup:
228.. code:: reST
230 Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
231 bar <reST anchor>`.
233.. admonition:: ``:ref:`` role
234 :class: rst-example
236 Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
237 bar <reST anchor>`.
239.. _reST ordinary ref:
241Link ordinary URL
242-----------------
244If you need to reference external URLs use *named* hyperlinks to maintain
245readability of reST sources. Here is a example taken from *this* article:
247.. code:: reST
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
253 readable.
255 And this shows the alternative (less readable) hyperlink markup `Sphinx Field
256 Lists
257 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
259.. admonition:: Named hyperlink
260 :class: rst-example
262 With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
263 readable.
265 And this shows the alternative (less readable) hyperlink markup `Sphinx Field
266 Lists
267 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
270.. _reST smart ref:
272Smart refs
273----------
275With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
276content becomes smart.
278.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
279 :widths: 4 3 7
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```
295 intersphinx_
296 --------------------------------------------------------------------------------------------------
297 external anchor :ref:`python:and` ``:ref:`python:and```
298 external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
299 python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
300 flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
301 ========================== ================================== ====================================
304Intersphinx is configured in :origin:`docs/conf.py`:
306.. code:: python
308 intersphinx_mapping = {
309 "python": ("https://docs.python.org/3/", None),
310 "flask": ("https://flask.palletsprojects.com/", None),
311 "jinja": ("https://jinja.palletsprojects.com/", None),
312 "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
313 "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
314 }
317To list all anchors of the inventory (e.g. ``python``) use:
319.. code:: sh
321 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
323Literal blocks
324==============
326The simplest form of :duref:`literal-blocks` is a indented block introduced by
327two colons (``::``). For highlighting use :dudir:`highlight` or :ref:`reST
328code` directive. To include literals from external files use directive
329:dudir:`literalinclude`.
331.. _reST literal:
333``::``
334------
336.. code:: reST
338 ::
340 Literal block
342 Lorem ipsum dolor::
344 Literal block
346 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
347 eirmod tempor invidunt ut labore ::
349 Literal block
351.. admonition:: Literal block
352 :class: rst-example
354 ::
356 Literal block
358 Lorem ipsum dolor::
360 Literal block
362 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
363 eirmod tempor invidunt ut labore ::
365 Literal block
368.. _reST code:
370``code-block``
371--------------
373.. _pygments: https://pygments.org/languages/
375.. sidebar:: Syntax highlighting
377 is handled by pygments_.
379The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
380with additional options. To learn more about code literals visit
381:ref:`sphinx:code-examples`.
383.. code-block:: reST
385 The URL ``/stats`` handle is shown in :ref:`stats-handle`
387 .. code-block:: Python
388 :caption: python code block
389 :name: stats-handle
391 @app.route('/stats', methods=['GET'])
392 def stats():
393 """Render engine statistics page."""
394 stats = get_engines_stats()
395 return render(
396 'stats.html'
397 , stats = stats )
399.. code-block:: reST
401.. admonition:: Code block
402 :class: rst-example
404 The URL ``/stats`` handle is shown in :ref:`stats-handle`
406 .. code-block:: Python
407 :caption: python code block
408 :name: stats-handle
410 @app.route('/stats', methods=['GET'])
411 def stats():
412 """Render engine statistics page."""
413 stats = get_engines_stats()
414 return render(
415 'stats.html'
416 , stats = stats )
418Unicode substitution
419====================
421The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
422character codes (numerical values) to characters. This directive can only be
423used within a substitution definition.
425.. code-block:: reST
427 .. |copy| unicode:: 0xA9 .. copyright sign
428 .. |(TM)| unicode:: U+2122
430 Trademark |(TM)| and copyright |copy| glyphs.
432.. admonition:: Unicode
433 :class: rst-example
435 .. |copy| unicode:: 0xA9 .. copyright sign
436 .. |(TM)| unicode:: U+2122
438 Trademark |(TM)| and copyright |copy| glyphs.
441.. _reST roles:
443Roles
444=====
446.. sidebar:: Further reading
448 - `Sphinx Roles`_
449 - :doc:`sphinx:usage/restructuredtext/domains`
452A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
453explicit markup. It signifies that that the enclosed text should be interpreted
454in a specific way.
456The general markup is one of:
458.. code:: reST
460 :rolename:`ref-name`
461 :rolename:`ref text <ref-name>`
463.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
464 :widths: 4 3 7
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 ========================== ================================== ====================================
484Figures & Images
485================
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_.
493Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
494scaleable in sense of the build process. Normally in absence of a converter
495tool, the build process will break. From the authors POV it’s annoying to care
496about the build process when handling with images, especially since he has no
497access to the build process. With :ref:`linuxdoc:kfigure` the build process
498continues and scales output quality in dependence of installed image processors.
500If you want to add an image, you should use the ``kernel-figure`` (inheritance
501of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
502directives. E.g. to insert a figure with a scaleable image format use SVG
503(:ref:`svg image example`):
505.. code:: reST
507 .. _svg image example:
509 .. kernel-figure:: svg_image.svg
510 :alt: SVG image example
512 Simple SVG image
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
521 Simple SVG image.
523To refer the figure, a caption block is needed: :ref:`svg image example`.
525DOT files (aka Graphviz)
526------------------------
528With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
529given.
531- `Graphviz's dot`_
532- DOT_
533- Graphviz_
535A simple example is shown in :ref:`dot file example`:
537.. code:: reST
539 .. _dot file example:
541 .. kernel-figure:: hello.dot
542 :alt: hello world
544 DOT's hello world example
546.. admonition:: hello.dot
547 :class: rst-example
549 .. _dot file example:
551 .. kernel-figure:: hello.dot
552 :alt: hello world
554 DOT's hello world example
556``kernel-render`` DOT
557---------------------
559Embed *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
561shown in figure :ref:`dot render example`:
563.. code:: reST
565 .. _dot render example:
567 .. kernel-render:: DOT
568 :alt: digraph
569 :caption: Embedded DOT (Graphviz) code
571 digraph foo {
572 "bar" -> "baz";
573 }
575 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
576 render example`.
578Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
579installed, you will see an vector image. If not, the raw markup is inserted as
580*literal-block*.
582.. admonition:: kernel-render DOT
583 :class: rst-example
585 .. _dot render example:
587 .. kernel-render:: DOT
588 :alt: digraph
589 :caption: Embedded DOT (Graphviz) code
591 digraph foo {
592 "bar" -> "baz";
593 }
595 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
596 render example`.
598``kernel-render`` SVG
599---------------------
601A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
603.. code:: reST
605 .. _svg render example:
607 .. kernel-render:: SVG
608 :caption: Embedded **SVG** markup
609 :alt: so-nw-arrow
610..
612 .. code:: xml
614 <?xml version="1.0" encoding="UTF-8"?>
615 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
616 baseProfile="full" width="70px" height="40px"
617 viewBox="0 0 700 400"
618 >
619 <line x1="180" y1="370"
620 x2="500" y2="50"
621 stroke="black" stroke-width="15px"
622 />
623 <polygon points="585 0 525 25 585 50"
624 transform="rotate(135 525 25)"
625 />
626 </svg>
628.. admonition:: kernel-render SVG
629 :class: rst-example
631 .. _svg render example:
633 .. kernel-render:: SVG
634 :caption: Embedded **SVG** markup
635 :alt: so-nw-arrow
637 <?xml version="1.0" encoding="UTF-8"?>
638 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
639 baseProfile="full" width="70px" height="40px"
640 viewBox="0 0 700 400"
641 >
642 <line x1="180" y1="370"
643 x2="500" y2="50"
644 stroke="black" stroke-width="15px"
645 />
646 <polygon points="585 0 525 25 585 50"
647 transform="rotate(135 525 25)"
648 />
649 </svg>
654.. _reST lists:
656List markups
657============
659Bullet list
660-----------
662List markup (:duref:`ref <bullet-lists>`) is simple:
664.. code:: reST
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
679 :class: rst-example
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.
694Horizontal list
695---------------
697The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
698list.
700.. code:: reST
702 .. hlist::
704 - first list item
705 - second list item
706 - third list item
707 ...
709.. admonition:: hlist
710 :class: rst-example
712 .. hlist::
714 - first list item
715 - second list item
716 - third list item
717 - next list item
718 - next list item xxxx
719 - next list item yyyy
720 - next list item zzzz
723Definition list
724---------------
726.. sidebar:: Note ..
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>`).
734Each definition list (:duref:`ref <definition-lists>`) item contains a term,
735optional classifiers and a definition. A term is a simple one-line word or
736phrase. Optional classifiers may follow the term on the same line, each after
737an inline ' : ' (**space, colon, space**). A definition is a block indented
738relative to the term, and may contain multiple paragraphs and other body
739elements. 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
741required before the first and after the last definition list item, but are
742optional in-between.
744Definition lists are created as follows:
746.. code:: reST
748 term 1 (up to a line of text)
749 Definition 1.
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!
757 term 2
758 Definition 2, paragraph 1.
760 Definition 2, paragraph 2.
762 term 3 : classifier
763 Definition 3.
765 term 4 : classifier one : classifier two
766 Definition 4.
768.. admonition:: definition list
769 :class: rst-example
771 term 1 (up to a line of text)
772 Definition 1.
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!
781 term 2
782 Definition 2, paragraph 1.
784 Definition 2, paragraph 2.
786 term 3 : classifier
787 Definition 3.
789 term 4 : classifier one : classifier two
792Quoted paragraphs
793-----------------
795Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
796them more than the surrounding paragraphs. Line blocks (:duref:`ref
797<line-blocks>`) are a way of preserving line breaks:
799.. code:: reST
801 normal paragraph ...
802 lorem ipsum.
804 Quoted paragraph ...
805 lorem ipsum.
807 | These lines are
808 | broken exactly like in
809 | the source file.
812.. admonition:: Quoted paragraph and line block
813 :class: rst-example
815 normal paragraph ...
816 lorem ipsum.
818 Quoted paragraph ...
819 lorem ipsum.
821 | These lines are
822 | broken exactly like in
823 | the source file.
826.. _reST field list:
828Field Lists
829-----------
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`_.
838Field lists are used as part of an extension syntax, such as options for
839directives, or database-like records meant for further processing. Field lists
840are mappings from field names to field bodies. They marked up like this:
842.. code:: reST
844 :fieldname: Field content
845 :foo: first paragraph in field foo
847 second paragraph in field foo
849 :bar: Field content
851.. admonition:: Field List
852 :class: rst-example
854 :fieldname: Field content
855 :foo: first paragraph in field foo
857 second paragraph in field foo
859 :bar: Field content
862They are commonly used in Python documentation:
864.. code:: python
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).
873 """
875Further list blocks
876-------------------
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>`)
885Admonitions
886===========
888Sidebar
889-------
891Sidebar is an eye catcher, often used for admonitions pointing further stuff or
892site effects. Here is the source of the sidebar :ref:`on top of this page <reST
893primer>`.
895.. code:: 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_.
902Generic admonition
903------------------
905The generic :dudir:`admonition <admonitions>` needs a title:
907.. code:: reST
909 .. admonition:: generic admonition title
911 lorem ipsum ..
914.. admonition:: generic admonition title
916 lorem ipsum ..
919Specific admonitions
920--------------------
922Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
923:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
924:dudir:`warning` .
926.. code:: reST
928 .. hint::
930 lorem ipsum ..
932 .. note::
934 lorem ipsum ..
936 .. warning::
938 lorem ipsum ..
941.. hint::
943 lorem ipsum ..
945.. note::
947 lorem ipsum ..
949.. tip::
951 lorem ipsum ..
953.. attention::
955 lorem ipsum ..
957.. caution::
959 lorem ipsum ..
961.. danger::
963 lorem ipsum ..
965.. important::
967 lorem ipsum ..
969.. error::
971 lorem ipsum ..
973.. warning::
975 lorem ipsum ..
978Tables
979======
981.. sidebar:: Nested tables
983 Nested tables are ugly! Not all builder support nested tables, don't use
984 them!
986ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
987be comfortable for readers of the text-files, but they have huge disadvantages
988in the creation and modifying. First, they are hard to edit. Think about
989adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
990it is a nightmare on big tables.
993.. sidebar:: List tables
995 For meaningful patch and diff use :ref:`reST flat table`.
997Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
998cell generates a diff in which also changes are included, which are only
999ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
1000here are some helpers:
1002* `Emacs Table Mode`_
1003* `Online Tables Generator`_
1005.. _reST simple table:
1007Simple tables
1008-------------
1010:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
1011your table need some metadata (e.g. a title) you need to add the ``.. table::
1012directive`` :dudir:`(ref) <table>` in front and place the table in its body:
1014.. code:: reST
1016 .. table:: foo gate truth table
1017 :widths: grid
1018 :align: left
1020 ====== ====== ======
1021 Inputs Output
1022 ------------- ------
1023 A B A or B
1024 ====== ====== ======
1025 False
1026 --------------------
1027 True
1028 --------------------
1029 True False True
1030 (foo)
1031 ------ ------ ------
1032 False True
1033 (foo)
1034 ====== =============
1036.. admonition:: Simple ASCII table
1037 :class: rst-example
1039 .. table:: foo gate truth table
1040 :widths: grid
1041 :align: left
1043 ====== ====== ======
1044 Inputs Output
1045 ------------- ------
1046 A B A or B
1047 ====== ====== ======
1048 False
1049 --------------------
1050 True
1051 --------------------
1052 True False True
1053 (foo)
1054 ------ ------ ------
1055 False True
1056 (foo)
1057 ====== =============
1061.. _reST grid table:
1063Grid tables
1064-----------
1066:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
1068.. code:: reST
1070 .. table:: grid table example
1071 :widths: 1 1 5
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
1089 :widths: 1 1 5
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:
1106flat-table
1107----------
1109The ``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:
1113column-span: ``cspan``
1114 with the role ``cspan`` a cell can be extended through additional columns
1116row-span: ``rspan``
1117 with the role ``rspan`` a cell can be extended through additional rows
1119auto-span:
1120 spans rightmost cell of a table row over the missing cells on the right side
1121 of that table-row. With Option ``:fill-cells:`` this behavior can changed
1122 from *auto span* to *auto fill*, which automatically inserts (empty) cells
1123 instead of spanning the last cell.
1125options:
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
1131roles:
1132 :cspan: [int] additional columns (*morecols*)
1133 :rspan: [int] additional rows (*morerows*)
1135The example below shows how to use this markup. The first level of the staged
1136list is the *table-row*. In the *table-row* there is only one markup allowed,
1137the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
1138and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
1140.. code:: reST
1142 .. flat-table:: ``flat-table`` example
1143 :header-rows: 2
1144 :stub-columns: 1
1145 :widths: 1 1 1 1 2
1147 * - :rspan:`1` head / stub
1148 - :cspan:`3` head 1.1-4
1150 * - head 2.1
1151 - head 2.2
1152 - head 2.3
1153 - head 2.4
1155 * .. row body 1 / this is a comment
1157 - row 1
1158 - :rspan:`2` cell 1-3.1
1159 - cell 1.2
1160 - cell 1.3
1161 - cell 1.4
1163 * .. Comments and targets are allowed on *table-row* stage.
1164 .. _`row body 2`:
1166 - row 2
1167 - cell 2.2
1168 - :rspan:`1` :cspan:`1`
1169 cell 2.3 with a span over
1171 * col 3-4 &
1172 * row 2-3
1174 * - row 3
1175 - cell 3.2
1177 * - row 4
1178 - cell 4.1
1179 - cell 4.2
1180 - cell 4.3
1181 - cell 4.4
1183 * - row 5
1184 - cell 5.1 with automatic span to rigth end
1186 * - row 6
1187 - cell 6.1
1188 - ..
1191.. admonition:: List table
1192 :class: rst-example
1194 .. flat-table:: ``flat-table`` example
1195 :header-rows: 2
1196 :stub-columns: 1
1197 :widths: 1 1 1 1 2
1199 * - :rspan:`1` head / stub
1200 - :cspan:`3` head 1.1-4
1202 * - head 2.1
1203 - head 2.2
1204 - head 2.3
1205 - head 2.4
1207 * .. row body 1 / this is a comment
1209 - row 1
1210 - :rspan:`2` cell 1-3.1
1211 - cell 1.2
1212 - cell 1.3
1213 - cell 1.4
1215 * .. Comments and targets are allowed on *table-row* stage.
1216 .. _`row body 2`:
1218 - row 2
1219 - cell 2.2
1220 - :rspan:`1` :cspan:`1`
1221 cell 2.3 with a span over
1223 * col 3-4 &
1224 * row 2-3
1226 * - row 3
1227 - cell 3.2
1229 * - row 4
1230 - cell 4.1
1231 - cell 4.2
1232 - cell 4.3
1233 - cell 4.4
1235 * - row 5
1236 - cell 5.1 with automatic span to rigth end
1238 * - row 6
1239 - cell 6.1
1240 - ..
1243CSV table
1244---------
1246CSV table might be the choice if you want to include CSV-data from a outstanding
1247(build) process into your documentation.
1249.. code:: reST
1251 .. csv-table:: CSV table example
1252 :header: .. , Column 1, Column 2
1253 :widths: 2 5 5
1254 :stub-columns: 1
1255 :file: csv_table.txt
1257Content 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
1266 :widths: 3 5 5
1267 :stub-columns: 1
1268 :file: csv_table.txt
1270Templating
1271==========
1273.. sidebar:: Build environment
1275 All *generic-doc* tasks are running in the :ref:`build environment <make
1276 pyenv>`.
1278Templating is suitable for documentation which is created generic at the build
1279time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
1280environment <make pyenv>` (with searx modules installed). We use this e.g. to
1281build chapter: :ref:`engines generic`. Below the jinja directive from the
1282:origin:`docs/admin/engines.rst` is shown:
1284.. literalinclude:: ../admin/engines.rst
1285 :language: reST
1286 :start-after: .. _configured engines:
1288The context for the template is selected in the line ``.. jinja:: webapp``. In
1289sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
1290points to the name space of the python module: ``webapp``.
1292.. code:: py
1294 from searx import webapp
1295 jinja_contexts = {
1296 'webapp': dict(**webapp.__dict__)
1300Tabbed views
1301============
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
1308With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1309instructions with one tab per distribution we use the `group-tabs`_ directive,
1310others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1311:ref:`docs build` is shown:
1313.. literalinclude:: ../admin/buildhosts.rst
1314 :language: reST
1315 :start-after: .. _system requirements:
1316 :end-before: .. _system requirements END:
1319.. _math:
1321Math equations
1322==============
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`_
1331 - Mathematics_
1332 - :ref:`docs build`
1334The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
1335package.
1337To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
1338inline and directive :rst:dir:`.. math:: <math>` for block markup.
1340.. code:: reST
1342 In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1343 is shown.
1345 .. math::
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
1355 is shown.
1357 .. math::
1358 :label: schroedinger general
1360 \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1361 \hat{H} |\,\psi (t) \rangle.
1364The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1365(*displaystyle*) used in a inline markup or another fraction.
1367.. code:: reST
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
1377 voluptua. ...
1378 ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
1379 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1380 gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
1382 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
1383 eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
1384 voluptua. ...
1385 ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
1386 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1387 gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
1390.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1392.. _readability: https://docs.python-guide.org/writing/style/
1393.. _Sphinx-Primer:
1394 http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
1395.. _reST: https://docutils.sourceforge.io/rst.html
1396.. _Sphinx Roles:
1397 https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
1398.. _Sphinx: http://www.sphinx-doc.org
1399.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html
1400.. _Sphinx markup constructs:
1401 http://www.sphinx-doc.org/en/stable/markup/index.html
1402.. _`sphinx cross references`:
1403 http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
1404.. _sphinx.ext.extlinks:
1405 https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
1406.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
1407.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html
1408.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
1409.. _Sphinx's Python domain:
1410 http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
1411.. _Sphinx's C domain:
1412 http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
1413.. _doctree:
1414 http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
1415.. _docutils: http://docutils.sourceforge.net/docs/index.html
1416.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
1417.. _linuxdoc: https://return42.github.io/linuxdoc
1418.. _jinja: https://jinja.palletsprojects.com/
1419.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
1420.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
1421.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
1422.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
1423.. _Graphviz: https://graphviz.gitlab.io
1424.. _ImageMagick: https://www.imagemagick.org
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