git.iko.soy/searx
on fce2d49 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:`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
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
329:rst:dir:`literalinclude` or :ref:`kernel-include <kernel-include-directive>`
330directive (latter one expands environment variables in the path name).
332.. _reST literal:
334``::``
335------
337.. code:: reST
339 ::
341 Literal block
343 Lorem ipsum dolor::
345 Literal block
347 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
348 eirmod tempor invidunt ut labore ::
350 Literal block
352.. admonition:: Literal block
353 :class: rst-example
355 ::
357 Literal block
359 Lorem ipsum dolor::
361 Literal block
363 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
364 eirmod tempor invidunt ut labore ::
366 Literal block
369.. _reST code:
371``code-block``
372--------------
374.. _pygments: https://pygments.org/languages/
376.. sidebar:: Syntax highlighting
378 is handled by pygments_.
380The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
381with additional options. To learn more about code literals visit
382:ref:`sphinx:code-examples`.
384.. code-block:: reST
386 The URL ``/stats`` handle is shown in :ref:`stats-handle`
388 .. code-block:: Python
389 :caption: python code block
390 :name: stats-handle
392 @app.route('/stats', methods=['GET'])
393 def stats():
394 """Render engine statistics page."""
395 stats = get_engines_stats()
396 return render(
397 'stats.html'
398 , stats = stats )
400.. code-block:: reST
402.. admonition:: Code block
403 :class: rst-example
405 The URL ``/stats`` handle is shown in :ref:`stats-handle`
407 .. code-block:: Python
408 :caption: python code block
409 :name: stats-handle
411 @app.route('/stats', methods=['GET'])
412 def stats():
413 """Render engine statistics page."""
414 stats = get_engines_stats()
415 return render(
416 'stats.html'
417 , stats = stats )
419Unicode substitution
420====================
422The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
423character codes (numerical values) to characters. This directive can only be
424used within a substitution definition.
426.. code-block:: reST
428 .. |copy| unicode:: 0xA9 .. copyright sign
429 .. |(TM)| unicode:: U+2122
431 Trademark |(TM)| and copyright |copy| glyphs.
433.. admonition:: Unicode
434 :class: rst-example
436 .. |copy| unicode:: 0xA9 .. copyright sign
437 .. |(TM)| unicode:: U+2122
439 Trademark |(TM)| and copyright |copy| glyphs.
442.. _reST roles:
444Roles
445=====
447.. sidebar:: Further reading
449 - `Sphinx Roles`_
450 - :doc:`sphinx:usage/restructuredtext/domains`
453A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
454explicit markup. It signifies that that the enclosed text should be interpreted
455in a specific way.
457The general markup is one of:
459.. code:: reST
461 :rolename:`ref-name`
462 :rolename:`ref text <ref-name>`
464.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
465 :widths: 4 3 7
467 ========================== ================================== ====================================
468 role rendered example markup
469 ========================== ================================== ====================================
470 :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
471 :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
472 :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
473 :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
474 math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
475 :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
476 :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
477 :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
478 :durole:`strong` :strong:`bold` ``:strong:`bold```
479 :durole:`literal` :literal:`foo()` ``:literal:`foo()```
480 :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
481 :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
482 :durole:`title-reference` :title:`Time` ``:title:`Time```
483 ========================== ================================== ====================================
485Figures & Images
486================
488.. sidebar:: Image processing
490 With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
491 is flexible. To get best results in the generated output format, install
492 ImageMagick_ and Graphviz_.
494Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
495scaleable in sense of the build process. Normally in absence of a converter
496tool, the build process will break. From the authors POV it’s annoying to care
497about the build process when handling with images, especially since he has no
498access to the build process. With :ref:`linuxdoc:kfigure` the build process
499continues and scales output quality in dependence of installed image processors.
501If you want to add an image, you should use the ``kernel-figure`` (inheritance
502of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
503directives. E.g. to insert a figure with a scaleable image format use SVG
504(:ref:`svg image example`):
506.. code:: reST
508 .. _svg image example:
510 .. kernel-figure:: svg_image.svg
511 :alt: SVG image example
513 Simple SVG image
515 To refer the figure, a caption block is needed: :ref:`svg image example`.
517.. _svg image example:
519.. kernel-figure:: svg_image.svg
520 :alt: SVG image example
522 Simple SVG image.
524To refer the figure, a caption block is needed: :ref:`svg image example`.
526DOT files (aka Graphviz)
527------------------------
529With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
530given.
532- `Graphviz's dot`_
533- DOT_
534- Graphviz_
536A simple example is shown in :ref:`dot file example`:
538.. code:: reST
540 .. _dot file example:
542 .. kernel-figure:: hello.dot
543 :alt: hello world
545 DOT's hello world example
547.. admonition:: hello.dot
548 :class: rst-example
550 .. _dot file example:
552 .. kernel-figure:: hello.dot
553 :alt: hello world
555 DOT's hello world example
557``kernel-render`` DOT
558---------------------
560Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
561:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
562shown in figure :ref:`dot render example`:
564.. code:: reST
566 .. _dot render example:
568 .. kernel-render:: DOT
569 :alt: digraph
570 :caption: Embedded DOT (Graphviz) code
572 digraph foo {
573 "bar" -> "baz";
574 }
576 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
577 render example`.
579Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
580installed, you will see an vector image. If not, the raw markup is inserted as
581*literal-block*.
583.. admonition:: kernel-render DOT
584 :class: rst-example
586 .. _dot render example:
588 .. kernel-render:: DOT
589 :alt: digraph
590 :caption: Embedded DOT (Graphviz) code
592 digraph foo {
593 "bar" -> "baz";
594 }
596 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
597 render example`.
599``kernel-render`` SVG
600---------------------
602A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
604.. code:: reST
606 .. _svg render example:
608 .. kernel-render:: SVG
609 :caption: Embedded **SVG** markup
610 :alt: so-nw-arrow
611..
613 .. code:: xml
615 <?xml version="1.0" encoding="UTF-8"?>
616 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
617 baseProfile="full" width="70px" height="40px"
618 viewBox="0 0 700 400"
619 >
620 <line x1="180" y1="370"
621 x2="500" y2="50"
622 stroke="black" stroke-width="15px"
623 />
624 <polygon points="585 0 525 25 585 50"
625 transform="rotate(135 525 25)"
626 />
627 </svg>
629.. admonition:: kernel-render SVG
630 :class: rst-example
632 .. _svg render example:
634 .. kernel-render:: SVG
635 :caption: Embedded **SVG** markup
636 :alt: so-nw-arrow
638 <?xml version="1.0" encoding="UTF-8"?>
639 <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
640 baseProfile="full" width="70px" height="40px"
641 viewBox="0 0 700 400"
642 >
643 <line x1="180" y1="370"
644 x2="500" y2="50"
645 stroke="black" stroke-width="15px"
646 />
647 <polygon points="585 0 525 25 585 50"
648 transform="rotate(135 525 25)"
649 />
650 </svg>
655.. _reST lists:
657List markups
658============
660Bullet list
661-----------
663List markup (:duref:`ref <bullet-lists>`) is simple:
665.. code:: reST
667 - This is a bulleted list.
669 1. Nested lists are possible, but be aware that they must be separated from
670 the parent list items by blank line
671 2. Second item of nested list
673 - It has two items, the second
674 item uses two lines.
676 #. This is a numbered list.
677 #. It has two items too.
679.. admonition:: bullet list
680 :class: rst-example
682 - This is a bulleted list.
684 1. Nested lists are possible, but be aware that they must be separated from
685 the parent list items by blank line
686 2. Second item of nested list
688 - It has two items, the second
689 item uses two lines.
691 #. This is a numbered list.
692 #. It has two items too.
695Horizontal list
696---------------
698The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
699list.
701.. code:: reST
703 .. hlist::
705 - first list item
706 - second list item
707 - third list item
708 ...
710.. admonition:: hlist
711 :class: rst-example
713 .. hlist::
715 - first list item
716 - second list item
717 - third list item
718 - next list item
719 - next list item xxxx
720 - next list item yyyy
721 - next list item zzzz
724Definition list
725---------------
727.. sidebar:: Note ..
729 - the term cannot have more than one line of text
731 - there is **no blank line between term and definition block** // this
732 distinguishes definition lists (:duref:`ref <definition-lists>`) from block
733 quotes (:duref:`ref <block-quotes>`).
735Each definition list (:duref:`ref <definition-lists>`) item contains a term,
736optional classifiers and a definition. A term is a simple one-line word or
737phrase. Optional classifiers may follow the term on the same line, each after
738an inline ' : ' (**space, colon, space**). A definition is a block indented
739relative to the term, and may contain multiple paragraphs and other body
740elements. There may be no blank line between a term line and a definition block
741(*this distinguishes definition lists from block quotes*). Blank lines are
742required before the first and after the last definition list item, but are
743optional in-between.
745Definition lists are created as follows:
747.. code:: reST
749 term 1 (up to a line of text)
750 Definition 1.
752 See the typo : this line is not a term!
754 And this is not term's definition. **There is a blank line** in between
755 the line above and this paragraph. That's why this paragraph is taken as
756 **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
758 term 2
759 Definition 2, paragraph 1.
761 Definition 2, paragraph 2.
763 term 3 : classifier
764 Definition 3.
766 term 4 : classifier one : classifier two
767 Definition 4.
769.. admonition:: definition list
770 :class: rst-example
772 term 1 (up to a line of text)
773 Definition 1.
775 See the typo : this line is not a term!
777 And this is not term's definition. **There is a blank line** in between
778 the line above and this paragraph. That's why this paragraph is taken as
779 **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
782 term 2
783 Definition 2, paragraph 1.
785 Definition 2, paragraph 2.
787 term 3 : classifier
788 Definition 3.
790 term 4 : classifier one : classifier two
793Quoted paragraphs
794-----------------
796Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
797them more than the surrounding paragraphs. Line blocks (:duref:`ref
798<line-blocks>`) are a way of preserving line breaks:
800.. code:: reST
802 normal paragraph ...
803 lorem ipsum.
805 Quoted paragraph ...
806 lorem ipsum.
808 | These lines are
809 | broken exactly like in
810 | the source file.
813.. admonition:: Quoted paragraph and line block
814 :class: rst-example
816 normal paragraph ...
817 lorem ipsum.
819 Quoted paragraph ...
820 lorem ipsum.
822 | These lines are
823 | broken exactly like in
824 | the source file.
827.. _reST field list:
829Field Lists
830-----------
832.. _Sphinx Field Lists:
833 https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
835.. sidebar:: bibliographic fields
837 First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
839Field lists are used as part of an extension syntax, such as options for
840directives, or database-like records meant for further processing. Field lists
841are mappings from field names to field bodies. They marked up like this:
843.. code:: reST
845 :fieldname: Field content
846 :foo: first paragraph in field foo
848 second paragraph in field foo
850 :bar: Field content
852.. admonition:: Field List
853 :class: rst-example
855 :fieldname: Field content
856 :foo: first paragraph in field foo
858 second paragraph in field foo
860 :bar: Field content
863They are commonly used in Python documentation:
865.. code:: python
867 def my_function(my_arg, my_other_arg):
868 """A function just for me.
870 :param my_arg: The first of my arguments.
871 :param my_other_arg: The second of my arguments.
873 :returns: A message (just for me, of course).
874 """
876Further list blocks
877-------------------
879- field lists (:duref:`ref <field-lists>`, with caveats noted in
880 :ref:`reST field list`)
881- option lists (:duref:`ref <option-lists>`)
882- quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
883- doctest blocks (:duref:`ref <doctest-blocks>`)
886Admonitions
887===========
889Sidebar
890-------
892Sidebar is an eye catcher, often used for admonitions pointing further stuff or
893site effects. Here is the source of the sidebar :ref:`on top of this page <reST
894primer>`.
896.. code:: reST
898 .. sidebar:: KISS_ and readability_
900 Instead of defining more and more roles, we at searx encourage our
901 contributors to follow principles like KISS_ and readability_.
903Generic admonition
904------------------
906The generic :dudir:`admonition <admonitions>` needs a title:
908.. code:: reST
910 .. admonition:: generic admonition title
912 lorem ipsum ..
915.. admonition:: generic admonition title
917 lorem ipsum ..
920Specific admonitions
921--------------------
923Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
924:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
925:dudir:`warning` .
927.. code:: reST
929 .. hint::
931 lorem ipsum ..
933 .. note::
935 lorem ipsum ..
937 .. warning::
939 lorem ipsum ..
942.. hint::
944 lorem ipsum ..
946.. note::
948 lorem ipsum ..
950.. tip::
952 lorem ipsum ..
954.. attention::
956 lorem ipsum ..
958.. caution::
960 lorem ipsum ..
962.. danger::
964 lorem ipsum ..
966.. important::
968 lorem ipsum ..
970.. error::
972 lorem ipsum ..
974.. warning::
976 lorem ipsum ..
979Tables
980======
982.. sidebar:: Nested tables
984 Nested tables are ugly! Not all builder support nested tables, don't use
985 them!
987ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
988be comfortable for readers of the text-files, but they have huge disadvantages
989in the creation and modifying. First, they are hard to edit. Think about
990adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
991it is a nightmare on big tables.
994.. sidebar:: List tables
996 For meaningful patch and diff use :ref:`reST flat table`.
998Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
999cell generates a diff in which also changes are included, which are only
1000ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
1001here are some helpers:
1003* `Emacs Table Mode`_
1004* `Online Tables Generator`_
1006.. _reST simple table:
1008Simple tables
1009-------------
1011:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
1012your table need some metadata (e.g. a title) you need to add the ``.. table::
1013directive`` :dudir:`(ref) <table>` in front and place the table in its body:
1015.. code:: reST
1017 .. table:: foo gate truth table
1018 :widths: grid
1019 :align: left
1021 ====== ====== ======
1022 Inputs Output
1023 ------------- ------
1024 A B A or B
1025 ====== ====== ======
1026 False
1027 --------------------
1028 True
1029 --------------------
1030 True False True
1031 (foo)
1032 ------ ------ ------
1033 False True
1034 (foo)
1035 ====== =============
1037.. admonition:: Simple ASCII table
1038 :class: rst-example
1040 .. table:: foo gate truth table
1041 :widths: grid
1042 :align: left
1044 ====== ====== ======
1045 Inputs Output
1046 ------------- ------
1047 A B A or B
1048 ====== ====== ======
1049 False
1050 --------------------
1051 True
1052 --------------------
1053 True False True
1054 (foo)
1055 ------ ------ ------
1056 False True
1057 (foo)
1058 ====== =============
1062.. _reST grid table:
1064Grid tables
1065-----------
1067:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
1069.. code:: reST
1071 .. table:: grid table example
1072 :widths: 1 1 5
1074 +------------+------------+-----------+
1075 | Header 1 | Header 2 | Header 3 |
1076 +============+============+===========+
1077 | body row 1 | column 2 | column 3 |
1078 +------------+------------+-----------+
1079 | body row 2 | Cells may span columns.|
1080 +------------+------------+-----------+
1081 | body row 3 | Cells may | - Cells |
1082 +------------+ span rows. | - contain |
1083 | body row 4 | | - blocks. |
1084 +------------+------------+-----------+
1086.. admonition:: ASCII grid table
1087 :class: rst-example
1089 .. table:: grid table example
1090 :widths: 1 1 5
1092 +------------+------------+-----------+
1093 | Header 1 | Header 2 | Header 3 |
1094 +============+============+===========+
1095 | body row 1 | column 2 | column 3 |
1096 +------------+------------+-----------+
1097 | body row 2 | Cells may span columns.|
1098 +------------+------------+-----------+
1099 | body row 3 | Cells may | - Cells |
1100 +------------+ span rows. | - contain |
1101 | body row 4 | | - blocks. |
1102 +------------+------------+-----------+
1105.. _reST flat table:
1107flat-table
1108----------
1110The ``flat-table`` is a further developed variant of the :ref:`list tables
1111<linuxdoc:list-table-directives>`. It is a double-stage list similar to the
1112:dudir:`list-table` with some additional features:
1114column-span: ``cspan``
1115 with the role ``cspan`` a cell can be extended through additional columns
1117row-span: ``rspan``
1118 with the role ``rspan`` a cell can be extended through additional rows
1120auto-span:
1121 spans rightmost cell of a table row over the missing cells on the right side
1122 of that table-row. With Option ``:fill-cells:`` this behavior can changed
1123 from *auto span* to *auto fill*, which automatically inserts (empty) cells
1124 instead of spanning the last cell.
1126options:
1127 :header-rows: [int] count of header rows
1128 :stub-columns: [int] count of stub columns
1129 :widths: [[int] [int] ... ] widths of columns
1130 :fill-cells: instead of auto-span missing cells, insert missing cells
1132roles:
1133 :cspan: [int] additional columns (*morecols*)
1134 :rspan: [int] additional rows (*morerows*)
1136The example below shows how to use this markup. The first level of the staged
1137list is the *table-row*. In the *table-row* there is only one markup allowed,
1138the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
1139and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
1141.. code:: reST
1143 .. flat-table:: ``flat-table`` example
1144 :header-rows: 2
1145 :stub-columns: 1
1146 :widths: 1 1 1 1 2
1148 * - :rspan:`1` head / stub
1149 - :cspan:`3` head 1.1-4
1151 * - head 2.1
1152 - head 2.2
1153 - head 2.3
1154 - head 2.4
1156 * .. row body 1 / this is a comment
1158 - row 1
1159 - :rspan:`2` cell 1-3.1
1160 - cell 1.2
1161 - cell 1.3
1162 - cell 1.4
1164 * .. Comments and targets are allowed on *table-row* stage.
1165 .. _`row body 2`:
1167 - row 2
1168 - cell 2.2
1169 - :rspan:`1` :cspan:`1`
1170 cell 2.3 with a span over
1172 * col 3-4 &
1173 * row 2-3
1175 * - row 3
1176 - cell 3.2
1178 * - row 4
1179 - cell 4.1
1180 - cell 4.2
1181 - cell 4.3
1182 - cell 4.4
1184 * - row 5
1185 - cell 5.1 with automatic span to rigth end
1187 * - row 6
1188 - cell 6.1
1189 - ..
1192.. admonition:: List table
1193 :class: rst-example
1195 .. flat-table:: ``flat-table`` example
1196 :header-rows: 2
1197 :stub-columns: 1
1198 :widths: 1 1 1 1 2
1200 * - :rspan:`1` head / stub
1201 - :cspan:`3` head 1.1-4
1203 * - head 2.1
1204 - head 2.2
1205 - head 2.3
1206 - head 2.4
1208 * .. row body 1 / this is a comment
1210 - row 1
1211 - :rspan:`2` cell 1-3.1
1212 - cell 1.2
1213 - cell 1.3
1214 - cell 1.4
1216 * .. Comments and targets are allowed on *table-row* stage.
1217 .. _`row body 2`:
1219 - row 2
1220 - cell 2.2
1221 - :rspan:`1` :cspan:`1`
1222 cell 2.3 with a span over
1224 * col 3-4 &
1225 * row 2-3
1227 * - row 3
1228 - cell 3.2
1230 * - row 4
1231 - cell 4.1
1232 - cell 4.2
1233 - cell 4.3
1234 - cell 4.4
1236 * - row 5
1237 - cell 5.1 with automatic span to rigth end
1239 * - row 6
1240 - cell 6.1
1241 - ..
1244CSV table
1245---------
1247CSV table might be the choice if you want to include CSV-data from a outstanding
1248(build) process into your documentation.
1250.. code:: reST
1252 .. csv-table:: CSV table example
1253 :header: .. , Column 1, Column 2
1254 :widths: 2 5 5
1255 :stub-columns: 1
1256 :file: csv_table.txt
1258Content of file ``csv_table.txt``:
1260.. literalinclude:: csv_table.txt
1262.. admonition:: CSV table
1263 :class: rst-example
1265 .. csv-table:: CSV table example
1266 :header: .. , Column 1, Column 2
1267 :widths: 3 5 5
1268 :stub-columns: 1
1269 :file: csv_table.txt
1271Templating
1272==========
1274.. sidebar:: Build environment
1276 All *generic-doc* tasks are running in the :ref:`build environment <make
1277 pyenv>`.
1279Templating is suitable for documentation which is created generic at the build
1280time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
1281environment <make pyenv>` (with searx modules installed). We use this e.g. to
1282build chapter: :ref:`engines generic`. Below the jinja directive from the
1283:origin:`docs/admin/engines.rst` is shown:
1285.. literalinclude:: ../admin/engines.rst
1286 :language: reST
1287 :start-after: .. _configured engines:
1289The context for the template is selected in the line ``.. jinja:: webapp``. In
1290sphinx's build configuration (:origin:`docs/conf.py`) the ``webapp`` context
1291points to the name space of the python module: ``webapp``.
1293.. code:: py
1295 from searx import webapp
1296 jinja_contexts = {
1297 'webapp': dict(**webapp.__dict__)
1301Tabbed views
1302============
1304.. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
1305.. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
1306.. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
1307.. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs
1309With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
1310instructions with one tab per distribution we use the `group-tabs`_ directive,
1311others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
1312:ref:`docs build` is shown:
1314.. literalinclude:: ../admin/buildhosts.rst
1315 :language: reST
1316 :start-after: .. SNIP sh lint requirements
1317 :end-before: .. SNAP sh lint requirements
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