git.iko.soy/searx
on engine-data help sign in
searx/docs/dev/reST.rst
1437 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:`Offline-engines` ``:wiki:`Offline-engines```
289 to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
290 files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
291 pull request :pull:`1756` ``:pull:`1756```
292 patch :patch:`af2cae6` ``:patch:`af2cae6```
293 PyPi package :pypi:`searx` ``:pypi:`searx```
294 manual page man :man:`bash` ``:man:`bash```
295 intersphinx_
296 --------------------------------------------------------------------------------------------------
297 external anchor :ref:`python:and` ``:ref:`python:and```
298 external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
299 python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
300 flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
301 ========================== ================================== ====================================
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
322 ...
323 $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
324 ...
326Literal blocks
327==============
329The simplest form of :duref:`literal-blocks` is a indented block introduced by
330two colons (``::``). For highlighting use :dudir:`highlight` or :ref:`reST
331code` directive. To include literals from external files use
332:rst:dir:`literalinclude` or :ref:`kernel-include <kernel-include-directive>`
333directive (latter one expands environment variables in the path name).
335.. _reST literal:
337``::``
338------
340.. code:: reST
342 ::
344 Literal block
346 Lorem ipsum dolor::
348 Literal block
350 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
351 eirmod tempor invidunt ut labore ::
353 Literal block
355.. admonition:: Literal block
356 :class: rst-example
358 ::
360 Literal block
362 Lorem ipsum dolor::
364 Literal block
366 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
367 eirmod tempor invidunt ut labore ::
369 Literal block
372.. _reST code:
374``code-block``
375--------------
377.. _pygments: https://pygments.org/languages/
379.. sidebar:: Syntax highlighting
381 is handled by pygments_.
383The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
384with additional options. To learn more about code literals visit
385:ref:`sphinx:code-examples`.
387.. code-block:: reST
389 The URL ``/stats`` handle is shown in :ref:`stats-handle`
391 .. code-block:: Python
392 :caption: python code block
393 :name: stats-handle
395 @app.route('/stats', methods=['GET'])
396 def stats():
397 """Render engine statistics page."""
398 stats = get_engines_stats()
399 return render(
400 'stats.html'
401 , stats = stats )
403.. code-block:: reST
405.. admonition:: Code block
406 :class: rst-example
408 The URL ``/stats`` handle is shown in :ref:`stats-handle`
410 .. code-block:: Python
411 :caption: python code block
412 :name: stats-handle
414 @app.route('/stats', methods=['GET'])
415 def stats():
416 """Render engine statistics page."""
417 stats = get_engines_stats()
418 return render(
419 'stats.html'
420 , stats = stats )
422Unicode substitution
423====================
425The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
426character codes (numerical values) to characters. This directive can only be
427used within a substitution definition.
429.. code-block:: reST
431 .. |copy| unicode:: 0xA9 .. copyright sign
432 .. |(TM)| unicode:: U+2122
434 Trademark |(TM)| and copyright |copy| glyphs.
436.. admonition:: Unicode
437 :class: rst-example
439 .. |copy| unicode:: 0xA9 .. copyright sign
440 .. |(TM)| unicode:: U+2122
442 Trademark |(TM)| and copyright |copy| glyphs.
445.. _reST roles:
447Roles
448=====
450.. sidebar:: Further reading
452 - `Sphinx Roles`_
453 - :doc:`sphinx:usage/restructuredtext/domains`
456A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
457explicit markup. It signifies that that the enclosed text should be interpreted
458in a specific way.
460The general markup is one of:
462.. code:: reST
464 :rolename:`ref-name`
465 :rolename:`ref text <ref-name>`
467.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
468 :widths: 4 3 7
470 ========================== ================================== ====================================
471 role rendered example markup
472 ========================== ================================== ====================================
473 :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
474 :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
475 :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
476 :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
477 math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
478 :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
479 :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
480 :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
481 :durole:`strong` :strong:`bold` ``:strong:`bold```
482 :durole:`literal` :literal:`foo()` ``:literal:`foo()```
483 :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
484 :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
485 :durole:`title-reference` :title:`Time` ``:title:`Time```
486 ========================== ================================== ====================================
488Figures & Images
489================
491.. sidebar:: Image processing
493 With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
494 is flexible. To get best results in the generated output format, install
495 ImageMagick_ and Graphviz_.
497Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
498scaleable in sense of the build process. Normally in absence of a converter
499tool, the build process will break. From the authors POV it’s annoying to care
500about the build process when handling with images, especially since he has no
501access to the build process. With :ref:`linuxdoc:kfigure` the build process
502continues and scales output quality in dependence of installed image processors.
504If you want to add an image, you should use the ``kernel-figure`` (inheritance
505of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
506directives. E.g. to insert a figure with a scaleable image format use SVG
507(:ref:`svg image example`):
509.. code:: reST
511 .. _svg image example:
513 .. kernel-figure:: svg_image.svg
514 :alt: SVG image example
516 Simple SVG image
518 To refer the figure, a caption block is needed: :ref:`svg image example`.
520.. _svg image example:
522.. kernel-figure:: svg_image.svg
523 :alt: SVG image example
525 Simple SVG image.
527To refer the figure, a caption block is needed: :ref:`svg image example`.
529DOT files (aka Graphviz)
530------------------------
532With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
533given.
535- `Graphviz's dot`_
536- DOT_
537- Graphviz_
539A simple example is shown in :ref:`dot file example`:
541.. code:: reST
543 .. _dot file example:
545 .. kernel-figure:: hello.dot
546 :alt: hello world
548 DOT's hello world example
550.. admonition:: hello.dot
551 :class: rst-example
553 .. _dot file example:
555 .. kernel-figure:: hello.dot
556 :alt: hello world
558 DOT's hello world example
560``kernel-render`` DOT
561---------------------
563Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
564:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
565shown in figure :ref:`dot render example`:
567.. code:: reST
569 .. _dot render example:
571 .. kernel-render:: DOT
572 :alt: digraph
573 :caption: Embedded DOT (Graphviz) code
575 digraph foo {
576 "bar" -> "baz";
577 }
579 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
580 render example`.
582Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
583installed, you will see an vector image. If not, the raw markup is inserted as
584*literal-block*.
586.. admonition:: kernel-render DOT
587 :class: rst-example
589 .. _dot render example:
591 .. kernel-render:: DOT
592 :alt: digraph
593 :caption: Embedded DOT (Graphviz) code
595 digraph foo {
596 "bar" -> "baz";
597 }
599 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
600 render example`.
602``kernel-render`` SVG
603---------------------
605A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
607.. code:: reST
609 .. _svg render example:
611 .. kernel-render:: SVG
612 :caption: Embedded **SVG** markup
613 :alt: so-nw-arrow
614..
616 .. code:: xml
618 <?xml version="1.0" encoding="UTF-8"?>
619 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
620 baseProfile="full" width="70px" height="40px"
621 viewBox="0 0 700 400"
622 >
623 <line x1="180" y1="370"
624 x2="500" y2="50"
625 stroke="black" stroke-width="15px"
626 />
627 <polygon points="585 0 525 25 585 50"
628 transform="rotate(135 525 25)"
629 />
630 </svg>
632.. admonition:: kernel-render SVG
633 :class: rst-example
635 .. _svg render example:
637 .. kernel-render:: SVG
638 :caption: Embedded **SVG** markup
639 :alt: so-nw-arrow
641 <?xml version="1.0" encoding="UTF-8"?>
642 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
643 baseProfile="full" width="70px" height="40px"
644 viewBox="0 0 700 400"
645 >
646 <line x1="180" y1="370"
647 x2="500" y2="50"
648 stroke="black" stroke-width="15px"
649 />
650 <polygon points="585 0 525 25 585 50"
651 transform="rotate(135 525 25)"
652 />
653 </svg>
658.. _reST lists:
660List markups
661============
663Bullet list
664-----------
666List markup (:duref:`ref <bullet-lists>`) is simple:
668.. code:: reST
670 - This is a bulleted list.
672 1. Nested lists are possible, but be aware that they must be separated from
673 the parent list items by blank line
674 2. Second item of nested list
676 - It has two items, the second
677 item uses two lines.
679 #. This is a numbered list.
680 #. It has two items too.
682.. admonition:: bullet list
683 :class: rst-example
685 - This is a bulleted list.
687 1. Nested lists are possible, but be aware that they must be separated from
688 the parent list items by blank line
689 2. Second item of nested list
691 - It has two items, the second
692 item uses two lines.
694 #. This is a numbered list.
695 #. It has two items too.
698Horizontal list
699---------------
701The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
702list.
704.. code:: reST
706 .. hlist::
708 - first list item
709 - second list item
710 - third list item
711 ...
713.. admonition:: hlist
714 :class: rst-example
716 .. hlist::
718 - first list item
719 - second list item
720 - third list item
721 - next list item
722 - next list item xxxx
723 - next list item yyyy
724 - next list item zzzz
727Definition list
728---------------
730.. sidebar:: Note ..
732 - the term cannot have more than one line of text
734 - there is **no blank line between term and definition block** // this
735 distinguishes definition lists (:duref:`ref <definition-lists>`) from block
736 quotes (:duref:`ref <block-quotes>`).
738Each definition list (:duref:`ref <definition-lists>`) item contains a term,
739optional classifiers and a definition. A term is a simple one-line word or
740phrase. Optional classifiers may follow the term on the same line, each after
741an inline ' : ' (**space, colon, space**). A definition is a block indented
742relative to the term, and may contain multiple paragraphs and other body
743elements. There may be no blank line between a term line and a definition block
744(*this distinguishes definition lists from block quotes*). Blank lines are
745required before the first and after the last definition list item, but are
746optional in-between.
748Definition lists are created as follows:
750.. code:: reST
752 term 1 (up to a line of text)
753 Definition 1.
755 See the typo : this line is not a term!
757 And this is not term's definition. **There is a blank line** in between
758 the line above and this paragraph. That's why this paragraph is taken as
759 **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
761 term 2
762 Definition 2, paragraph 1.
764 Definition 2, paragraph 2.
766 term 3 : classifier
767 Definition 3.
769 term 4 : classifier one : classifier two
770 Definition 4.
772.. admonition:: definition list
773 :class: rst-example
775 term 1 (up to a line of text)
776 Definition 1.
778 See the typo : this line is not a term!
780 And this is not term's definition. **There is a blank line** in between
781 the line above and this paragraph. That's why this paragraph is taken as
782 **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
785 term 2
786 Definition 2, paragraph 1.
788 Definition 2, paragraph 2.
790 term 3 : classifier
791 Definition 3.
793 term 4 : classifier one : classifier two
796Quoted paragraphs
797-----------------
799Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
800them more than the surrounding paragraphs. Line blocks (:duref:`ref
801<line-blocks>`) are a way of preserving line breaks:
803.. code:: reST
805 normal paragraph ...
806 lorem ipsum.
808 Quoted paragraph ...
809 lorem ipsum.
811 | These lines are
812 | broken exactly like in
813 | the source file.
816.. admonition:: Quoted paragraph and line block
817 :class: rst-example
819 normal paragraph ...
820 lorem ipsum.
822 Quoted paragraph ...
823 lorem ipsum.
825 | These lines are
826 | broken exactly like in
827 | the source file.
830.. _reST field list:
832Field Lists
833-----------
835.. _Sphinx Field Lists:
836 https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
838.. sidebar:: bibliographic fields
840 First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
842Field lists are used as part of an extension syntax, such as options for
843directives, or database-like records meant for further processing. Field lists
844are mappings from field names to field bodies. They marked up like this:
846.. code:: reST
848 :fieldname: Field content
849 :foo: first paragraph in field foo
851 second paragraph in field foo
853 :bar: Field content
855.. admonition:: Field List
856 :class: rst-example
858 :fieldname: Field content
859 :foo: first paragraph in field foo
861 second paragraph in field foo
863 :bar: Field content
866They are commonly used in Python documentation:
868.. code:: python
870 def my_function(my_arg, my_other_arg):
871 """A function just for me.
873 :param my_arg: The first of my arguments.
874 :param my_other_arg: The second of my arguments.
876 :returns: A message (just for me, of course).
877 """
879Further list blocks
880-------------------
882- field lists (:duref:`ref <field-lists>`, with caveats noted in
883 :ref:`reST field list`)
884- option lists (:duref:`ref <option-lists>`)
885- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
886- doctest blocks (:duref:`ref <doctest-blocks>`)
889Admonitions
890===========
892Sidebar
893-------
895Sidebar is an eye catcher, often used for admonitions pointing further stuff or
896site effects. Here is the source of the sidebar :ref:`on top of this page <reST
897primer>`.
899.. code:: reST
901 .. sidebar:: KISS_ and readability_
903 Instead of defining more and more roles, we at searx encourage our
904 contributors to follow principles like KISS_ and readability_.
906Generic admonition
907------------------
909The generic :dudir:`admonition <admonitions>` needs a title:
911.. code:: reST
913 .. admonition:: generic admonition title
915 lorem ipsum ..
918.. admonition:: generic admonition title
920 lorem ipsum ..
923Specific admonitions
924--------------------
926Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
927:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
928:dudir:`warning` .
930.. code:: reST
932 .. hint::
934 lorem ipsum ..
936 .. note::
938 lorem ipsum ..
940 .. warning::
942 lorem ipsum ..
945.. hint::
947 lorem ipsum ..
949.. note::
951 lorem ipsum ..
953.. tip::
955 lorem ipsum ..
957.. attention::
959 lorem ipsum ..
961.. caution::
963 lorem ipsum ..
965.. danger::
967 lorem ipsum ..
969.. important::
971 lorem ipsum ..
973.. error::
975 lorem ipsum ..
977.. warning::
979 lorem ipsum ..
982Tables
983======
985.. sidebar:: Nested tables
987 Nested tables are ugly! Not all builder support nested tables, don't use
988 them!
990ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
991be comfortable for readers of the text-files, but they have huge disadvantages
992in the creation and modifying. First, they are hard to edit. Think about
993adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
994it is a nightmare on big tables.
997.. sidebar:: List tables
999 For meaningful patch and diff use :ref:`reST flat table`.
1001Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
1002cell generates a diff in which also changes are included, which are only
1003ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
1004here are some helpers:
1006* `Emacs Table Mode`_
1007* `Online Tables Generator`_
1009.. _reST simple table:
1011Simple tables
1012-------------
1014:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
1015your table need some metadata (e.g. a title) you need to add the ``.. table::
1016directive`` :dudir:`(ref) <table>` in front and place the table in its body:
1018.. code:: reST
1020 .. table:: foo gate truth table
1021 :widths: grid
1022 :align: left
1024 ====== ====== ======
1025 Inputs Output
1026 ------------- ------
1027 A B A or B
1028 ====== ====== ======
1029 False
1030 --------------------
1031 True
1032 --------------------
1033 True False True
1034 (foo)
1035 ------ ------ ------
1036 False True
1037 (foo)
1038 ====== =============
1040.. admonition:: Simple ASCII table
1041 :class: rst-example
1043 .. table:: foo gate truth table
1044 :widths: grid
1045 :align: left
1047 ====== ====== ======
1048 Inputs Output
1049 ------------- ------
1050 A B A or B
1051 ====== ====== ======
1052 False
1053 --------------------
1054 True
1055 --------------------
1056 True False True
1057 (foo)
1058 ------ ------ ------
1059 False True
1060 (foo)
1061 ====== =============
1065.. _reST grid table:
1067Grid tables
1068-----------
1070:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
1072.. code:: reST
1074 .. table:: grid table example
1075 :widths: 1 1 5
1077 +------------+------------+-----------+
1078 | Header 1 | Header 2 | Header 3 |
1079 +============+============+===========+
1080 | body row 1 | column 2 | column 3 |
1081 +------------+------------+-----------+
1082 | body row 2 | Cells may span columns.|
1083 +------------+------------+-----------+
1084 | body row 3 | Cells may | - Cells |
1085 +------------+ span rows. | - contain |
1086 | body row 4 | | - blocks. |
1087 +------------+------------+-----------+
1089.. admonition:: ASCII grid table
1090 :class: rst-example
1092 .. table:: grid table example
1093 :widths: 1 1 5
1095 +------------+------------+-----------+
1096 | Header 1 | Header 2 | Header 3 |
1097 +============+============+===========+
1098 | body row 1 | column 2 | column 3 |
1099 +------------+------------+-----------+
1100 | body row 2 | Cells may span columns.|
1101 +------------+------------+-----------+
1102 | body row 3 | Cells may | - Cells |
1103 +------------+ span rows. | - contain |
1104 | body row 4 | | - blocks. |
1105 +------------+------------+-----------+
1108.. _reST flat table:
1110flat-table
1111----------
1113The ``flat-table`` is a further developed variant of the :ref:`list tables
1114<linuxdoc:list-table-directives>`. It is a double-stage list similar to the
1115:dudir:`list-table` with some additional features:
1117column-span: ``cspan``
1118 with the role ``cspan`` a cell can be extended through additional columns
1120row-span: ``rspan``
1121 with the role ``rspan`` a cell can be extended through additional rows
1123auto-span:
1124 spans rightmost cell of a table row over the missing cells on the right side
1125 of that table-row. With Option ``:fill-cells:`` this behavior can changed
1126 from *auto span* to *auto fill*, which automatically inserts (empty) cells
1127 instead of spanning the last cell.
1129options:
1130 :header-rows: [int] count of header rows
1131 :stub-columns: [int] count of stub columns
1132 :widths: [[int] [int] ... ] widths of columns
1133 :fill-cells: instead of auto-span missing cells, insert missing cells
1135roles:
1136 :cspan: [int] additional columns (*morecols*)
1137 :rspan: [int] additional rows (*morerows*)
1139The example below shows how to use this markup. The first level of the staged
1140list is the *table-row*. In the *table-row* there is only one markup allowed,
1141the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
1142and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
1144.. code:: reST
1146 .. flat-table:: ``flat-table`` example
1147 :header-rows: 2
1148 :stub-columns: 1
1149 :widths: 1 1 1 1 2
1151 * - :rspan:`1` head / stub
1152 - :cspan:`3` head 1.1-4
1154 * - head 2.1
1155 - head 2.2
1156 - head 2.3
1157 - head 2.4
1159 * .. row body 1 / this is a comment
1161 - row 1
1162 - :rspan:`2` cell 1-3.1
1163 - cell 1.2
1164 - cell 1.3
1165 - cell 1.4
1167 * .. Comments and targets are allowed on *table-row* stage.
1168 .. _`row body 2`:
1170 - row 2
1171 - cell 2.2
1172 - :rspan:`1` :cspan:`1`
1173 cell 2.3 with a span over
1175 * col 3-4 &
1176 * row 2-3
1178 * - row 3
1179 - cell 3.2
1181 * - row 4
1182 - cell 4.1
1183 - cell 4.2
1184 - cell 4.3
1185 - cell 4.4
1187 * - row 5
1188 - cell 5.1 with automatic span to rigth end
1190 * - row 6
1191 - cell 6.1
1192 - ..
1195.. admonition:: List table
1196 :class: rst-example
1198 .. flat-table:: ``flat-table`` example
1199 :header-rows: 2
1200 :stub-columns: 1
1201 :widths: 1 1 1 1 2
1203 * - :rspan:`1` head / stub
1204 - :cspan:`3` head 1.1-4
1206 * - head 2.1
1207 - head 2.2
1208 - head 2.3
1209 - head 2.4
1211 * .. row body 1 / this is a comment
1213 - row 1
1214 - :rspan:`2` cell 1-3.1
1215 - cell 1.2
1216 - cell 1.3
1217 - cell 1.4
1219 * .. Comments and targets are allowed on *table-row* stage.
1220 .. _`row body 2`:
1222 - row 2
1223 - cell 2.2
1224 - :rspan:`1` :cspan:`1`
1225 cell 2.3 with a span over
1227 * col 3-4 &
1228 * row 2-3
1230 * - row 3
1231 - cell 3.2
1233 * - row 4
1234 - cell 4.1
1235 - cell 4.2
1236 - cell 4.3
1237 - cell 4.4
1239 * - row 5
1240 - cell 5.1 with automatic span to rigth end
1242 * - row 6
1243 - cell 6.1
1244 - ..
1247CSV table
1248---------
1250CSV table might be the choice if you want to include CSV-data from a outstanding
1251(build) process into your documentation.
1253.. code:: reST
1255 .. csv-table:: CSV table example
1256 :header: .. , Column 1, Column 2
1257 :widths: 2 5 5
1258 :stub-columns: 1
1259 :file: csv_table.txt
1261Content of file ``csv_table.txt``:
1263.. literalinclude:: csv_table.txt
1265.. admonition:: CSV table
1266 :class: rst-example
1268 .. csv-table:: CSV table example
1269 :header: .. , Column 1, Column 2
1270 :widths: 3 5 5
1271 :stub-columns: 1
1272 :file: csv_table.txt
1274Templating
1275==========
1277.. sidebar:: Build environment
1279 All *generic-doc* tasks are running in the :ref:`build environment <make
1280 pyenv>`.
1282Templating is suitable for documentation which is created generic at the build
1283time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
1284environment <make pyenv>` (with searx modules installed). We use this e.g. to
1285build chapter: :ref:`engines generic`. Below the jinja directive from the
1286:origin:`docs/admin/engines.rst` is shown:
1288.. literalinclude:: ../admin/engines.rst
1289 :language: reST
1290 :start-after: .. _configured engines:
1292The context for the template is selected in the line ``.. jinja:: searx``. In
1293sphinx's build configuration (:origin:`docs/conf.py`) the ``searx`` context
1294contains the ``engines`` and ``plugins``.
1296.. code:: py
1298 import searx.search
1299 import searx.engines
1300 import searx.plugins
1301 searx.search.initialize()
1302 jinja_contexts = {
1303 'searx': {
1304 'engines': searx.engines.engines,
1305 'plugins': searx.plugins.plugins
1306 },
1310Tabbed views
1311============
1313.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
1314.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
1315.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
1316.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs
1318With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1319instructions with one tab per distribution we use the `group-tabs`_ directive,
1320others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1321:ref:`docs build` is shown:
1323.. literalinclude:: ../admin/buildhosts.rst
1324 :language: reST
1325 :start-after: .. SNIP sh lint requirements
1326 :end-before: .. SNAP sh lint requirements
1328.. _math:
1330Math equations
1331==============
1333.. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics
1334.. _amsmath user guide:
1335 http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf
1337.. sidebar:: About LaTeX
1339 - `amsmath user guide`_
1340 - Mathematics_
1341 - :ref:`docs build`
1343The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
1344package.
1346To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
1347inline and directive :rst:dir:`.. math:: <math>` for block markup.
1349.. code:: reST
1351 In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1352 is shown.
1354 .. math::
1355 :label: schroedinger general
1357 \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1358 \hat{H} |\,\psi (t) \rangle.
1360.. admonition:: LaTeX math equation
1361 :class: rst-example
1363 In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
1364 is shown.
1366 .. math::
1367 :label: schroedinger general
1369 \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
1370 \hat{H} |\,\psi (t) \rangle.
1373The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
1374(*displaystyle*) used in a inline markup or another fraction.
1376.. code:: reST
1378 ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
1379 ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
1381.. admonition:: Line spacing
1382 :class: rst-example
1384 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
1385 eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
1386 voluptua. ...
1387 ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
1388 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1389 gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
1391 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
1392 eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
1393 voluptua. ...
1394 ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
1395 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
1396 gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
1399.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1401.. _readability: https://docs.python-guide.org/writing/style/
1402.. _Sphinx-Primer:
1403 https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
1404.. _reST: https://docutils.sourceforge.io/rst.html
1405.. _Sphinx Roles:
1406 https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
1407.. _Sphinx: https://www.sphinx-doc.org
1408.. _`sphinx-doc FAQ`: https://www.sphinx-doc.org/en/stable/faq.html
1409.. _Sphinx markup constructs:
1410 https://www.sphinx-doc.org/en/stable/markup/index.html
1411.. _`sphinx cross references`:
1412 https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
1413.. _sphinx.ext.extlinks:
1414 https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
1415.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
1416.. _sphinx config: https://www.sphinx-doc.org/en/stable/config.html
1417.. _Sphinx's autodoc: https://www.sphinx-doc.org/en/stable/ext/autodoc.html
1418.. _Sphinx's Python domain:
1419 https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
1420.. _Sphinx's C domain:
1421 https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
1422.. _doctree:
1423 https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
1424.. _docutils: http://docutils.sourceforge.net/docs/index.html
1425.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
1426.. _linuxdoc: https://return42.github.io/linuxdoc
1427.. _jinja: https://jinja.palletsprojects.com/
1428.. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
1429.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
1430.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
1431.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
1432.. _Graphviz: https://graphviz.gitlab.io
1433.. _ImageMagick: https://www.imagemagick.org
1435.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
1436.. _`Online Tables Generator`: https://www.tablesgenerator.com/text_tables
1437.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html