1.. _reST primer: 2 3=========== 4reST primer 5=========== 6 7.. sidebar:: KISS_ and readability_ 8 9 Instead of defining more and more roles, we at searx encourage our 10 contributors to follow principles like KISS_ and readability_. 11 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`. 16 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. 20 21.. sidebar:: Further reading 22 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_ 36 37 38.. contents:: Contents 39 :depth: 3 40 :local: 41 :backlinks: entry 42 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]`_. 45 46.. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html 47 48.. sidebar:: Content matters 49 50 The readability_ of the reST sources has its value, therefore we recommend to 51 make sparse usage of reST markup / .. content matters! 52 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). 58 59Soft skills 60=========== 61 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: 64 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. 70 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. 74 75User's POV: :origin:`docs/user` 76 A typical user knows about search engines and might have heard about 77 meta crawlers and privacy. 78 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. 82 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. 88 89.. _reST inline markup: 90 91Basic inline markup 92=================== 93 94.. sidebar:: Inline markup 95 96 - :ref:`reST roles` 97 - :ref:`reST smart ref` 98 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``). 102 103.. table:: basic inline markup 104 :widths: 4 3 7 105 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 ================================================ ==================== ======================== 114 115.. _reST basic structure: 116 117Basic article structure 118======================= 119 120The basic structure of an article makes use of heading adornments to markup 121chapter, sections and subsections. 122 123.. _reST template: 124 125reST template 126------------- 127 128reST template for an simple article: 129 130.. code:: reST 131 132 .. _doc refname: 133 134 ============== 135 Document title 136 ============== 137 138 Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read 139 :ref:`chapter refname`. 140 141 .. _chapter refname: 142 143 Chapter 144 ======= 145 146 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut 147 aliquid ex ea commodi consequat ... 148 149 .. _section refname: 150 151 Section 152 ------- 153 154 lorem .. 155 156 .. _subsection refname: 157 158 Subsection 159 ~~~~~~~~~~ 160 161 lorem .. 162 163 164Headings 165-------- 166 167#. title - with overline for document title: 168 169 .. code:: reST 170 171 ============== 172 Document title 173 ============== 174 175 176#. chapter - with anchor named ``anchor name``: 177 178 .. code:: reST 179 180 .. _anchor name: 181 182 Chapter 183 ======= 184 185#. section 186 187 .. code:: reST 188 189 Section 190 ------- 191 192#. subsection 193 194 .. code:: reST 195 196 Subsection 197 ~~~~~~~~~~ 198 199 200 201Anchors & Links 202=============== 203 204.. _reST anchor: 205 206Anchors 207------- 208 209.. _ref role: 210 https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref 211 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``: 216 217.. code:: reST 218 219 .. _reST anchor: 220 221 Anchors 222 ------- 223 224 To refer a point in the documentation a anchor is needed ... 225 226To refer anchors use the `ref role`_ markup: 227 228.. code:: reST 229 230 Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo 231 bar <reST anchor>`. 232 233.. admonition:: ``:ref:`` role 234 :class: rst-example 235 236 Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo 237 bar <reST anchor>`. 238 239.. _reST ordinary ref: 240 241Link ordinary URL 242----------------- 243 244If you need to reference external URLs use *named* hyperlinks to maintain 245readability of reST sources. Here is a example taken from *this* article: 246 247.. code:: reST 248 249 .. _Sphinx Field Lists: 250 https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html 251 252 With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more 253 readable. 254 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>`__. 258 259.. admonition:: Named hyperlink 260 :class: rst-example 261 262 With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more 263 readable. 264 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>`__. 268 269 270.. _reST smart ref: 271 272Smart refs 273---------- 274 275With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external 276content becomes smart. 277 278.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_ 279 :widths: 4 3 7 280 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 ========================== ================================== ==================================== 302 303 304Intersphinx is configured in :origin:`docs/conf.py`: 305 306.. code:: python 307 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 } 315 316 317To list all anchors of the inventory (e.g. ``python``) use: 318 319.. code:: sh 320 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 ... 325 326Literal blocks 327============== 328 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). 334 335.. _reST literal: 336 337``::`` 338------ 339 340.. code:: reST 341 342 :: 343 344 Literal block 345 346 Lorem ipsum dolor:: 347 348 Literal block 349 350 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy 351 eirmod tempor invidunt ut labore :: 352 353 Literal block 354 355.. admonition:: Literal block 356 :class: rst-example 357 358 :: 359 360 Literal block 361 362 Lorem ipsum dolor:: 363 364 Literal block 365 366 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy 367 eirmod tempor invidunt ut labore :: 368 369 Literal block 370 371 372.. _reST code: 373 374``code-block`` 375-------------- 376 377.. _pygments: https://pygments.org/languages/ 378 379.. sidebar:: Syntax highlighting 380 381 is handled by pygments_. 382 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`. 386 387.. code-block:: reST 388 389 The URL ``/stats`` handle is shown in :ref:`stats-handle` 390 391 .. code-block:: Python 392 :caption: python code block 393 :name: stats-handle 394 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 ) 402 403.. code-block:: reST 404 405.. admonition:: Code block 406 :class: rst-example 407 408 The URL ``/stats`` handle is shown in :ref:`stats-handle` 409 410 .. code-block:: Python 411 :caption: python code block 412 :name: stats-handle 413 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 ) 421 422Unicode substitution 423==================== 424 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. 428 429.. code-block:: reST 430 431 .. |copy| unicode:: 0xA9 .. copyright sign 432 .. |(TM)| unicode:: U+2122 433 434 Trademark |(TM)| and copyright |copy| glyphs. 435 436.. admonition:: Unicode 437 :class: rst-example 438 439 .. |copy| unicode:: 0xA9 .. copyright sign 440 .. |(TM)| unicode:: U+2122 441 442 Trademark |(TM)| and copyright |copy| glyphs. 443 444 445.. _reST roles: 446 447Roles 448===== 449 450.. sidebar:: Further reading 451 452 - `Sphinx Roles`_ 453 - :doc:`sphinx:usage/restructuredtext/domains` 454 455 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. 459 460The general markup is one of: 461 462.. code:: reST 463 464 :rolename:`ref-name` 465 :rolename:`ref text <ref-name>` 466 467.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_ 468 :widths: 4 3 7 469 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 ========================== ================================== ==================================== 487 488Figures & Images 489================ 490 491.. sidebar:: Image processing 492 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_. 496 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. 503 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`): 508 509.. code:: reST 510 511 .. _svg image example: 512 513 .. kernel-figure:: svg_image.svg 514 :alt: SVG image example 515 516 Simple SVG image 517 518 To refer the figure, a caption block is needed: :ref:`svg image example`. 519 520.. _svg image example: 521 522.. kernel-figure:: svg_image.svg 523 :alt: SVG image example 524 525 Simple SVG image. 526 527To refer the figure, a caption block is needed: :ref:`svg image example`. 528 529DOT files (aka Graphviz) 530------------------------ 531 532With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is 533given. 534 535- `Graphviz's dot`_ 536- DOT_ 537- Graphviz_ 538 539A simple example is shown in :ref:`dot file example`: 540 541.. code:: reST 542 543 .. _dot file example: 544 545 .. kernel-figure:: hello.dot 546 :alt: hello world 547 548 DOT's hello world example 549 550.. admonition:: hello.dot 551 :class: rst-example 552 553 .. _dot file example: 554 555 .. kernel-figure:: hello.dot 556 :alt: hello world 557 558 DOT's hello world example 559 560``kernel-render`` DOT 561--------------------- 562 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`: 566 567.. code:: reST 568 569 .. _dot render example: 570 571 .. kernel-render:: DOT 572 :alt: digraph 573 :caption: Embedded DOT (Graphviz) code 574 575 digraph foo { 576 "bar" -> "baz"; 577 } 578 579 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot 580 render example`. 581 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*. 585 586.. admonition:: kernel-render DOT 587 :class: rst-example 588 589 .. _dot render example: 590 591 .. kernel-render:: DOT 592 :alt: digraph 593 :caption: Embedded DOT (Graphviz) code 594 595 digraph foo { 596 "bar" -> "baz"; 597 } 598 599 Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot 600 render example`. 601 602``kernel-render`` SVG 603--------------------- 604 605A simple example of embedded SVG_ is shown in figure :ref:`svg render example`: 606 607.. code:: reST 608 609 .. _svg render example: 610 611 .. kernel-render:: SVG 612 :caption: Embedded **SVG** markup 613 :alt: so-nw-arrow 614.. 615 616 .. code:: xml 617 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> 631 632.. admonition:: kernel-render SVG 633 :class: rst-example 634 635 .. _svg render example: 636 637 .. kernel-render:: SVG 638 :caption: Embedded **SVG** markup 639 :alt: so-nw-arrow 640 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> 654 655 656 657 658.. _reST lists: 659 660List markups 661============ 662 663Bullet list 664----------- 665 666List markup (:duref:`ref <bullet-lists>`) is simple: 667 668.. code:: reST 669 670 - This is a bulleted list. 671 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 675 676 - It has two items, the second 677 item uses two lines. 678 679 #. This is a numbered list. 680 #. It has two items too. 681 682.. admonition:: bullet list 683 :class: rst-example 684 685 - This is a bulleted list. 686 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 690 691 - It has two items, the second 692 item uses two lines. 693 694 #. This is a numbered list. 695 #. It has two items too. 696 697 698Horizontal list 699--------------- 700 701The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact 702list. 703 704.. code:: reST 705 706 .. hlist:: 707 708 - first list item 709 - second list item 710 - third list item 711 ... 712 713.. admonition:: hlist 714 :class: rst-example 715 716 .. hlist:: 717 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 725 726 727Definition list 728--------------- 729 730.. sidebar:: Note .. 731 732 - the term cannot have more than one line of text 733 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>`). 737 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. 747 748Definition lists are created as follows: 749 750.. code:: reST 751 752 term 1 (up to a line of text) 753 Definition 1. 754 755 See the typo : this line is not a term! 756 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! 760 761 term 2 762 Definition 2, paragraph 1. 763 764 Definition 2, paragraph 2. 765 766 term 3 : classifier 767 Definition 3. 768 769 term 4 : classifier one : classifier two 770 Definition 4. 771 772.. admonition:: definition list 773 :class: rst-example 774 775 term 1 (up to a line of text) 776 Definition 1. 777 778 See the typo : this line is not a term! 779 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! 783 784 785 term 2 786 Definition 2, paragraph 1. 787 788 Definition 2, paragraph 2. 789 790 term 3 : classifier 791 Definition 3. 792 793 term 4 : classifier one : classifier two 794 795 796Quoted paragraphs 797----------------- 798 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: 802 803.. code:: reST 804 805 normal paragraph ... 806 lorem ipsum. 807 808 Quoted paragraph ... 809 lorem ipsum. 810 811 | These lines are 812 | broken exactly like in 813 | the source file. 814 815 816.. admonition:: Quoted paragraph and line block 817 :class: rst-example 818 819 normal paragraph ... 820 lorem ipsum. 821 822 Quoted paragraph ... 823 lorem ipsum. 824 825 | These lines are 826 | broken exactly like in 827 | the source file. 828 829 830.. _reST field list: 831 832Field Lists 833----------- 834 835.. _Sphinx Field Lists: 836 https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html 837 838.. sidebar:: bibliographic fields 839 840 First lines fields are bibliographic fields, see `Sphinx Field Lists`_. 841 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: 845 846.. code:: reST 847 848 :fieldname: Field content 849 :foo: first paragraph in field foo 850 851 second paragraph in field foo 852 853 :bar: Field content 854 855.. admonition:: Field List 856 :class: rst-example 857 858 :fieldname: Field content 859 :foo: first paragraph in field foo 860 861 second paragraph in field foo 862 863 :bar: Field content 864 865 866They are commonly used in Python documentation: 867 868.. code:: python 869 870 def my_function(my_arg, my_other_arg): 871 """A function just for me. 872 873 :param my_arg: The first of my arguments. 874 :param my_other_arg: The second of my arguments. 875 876 :returns: A message (just for me, of course). 877 """ 878 879Further list blocks 880------------------- 881 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>`) 887 888 889Admonitions 890=========== 891 892Sidebar 893------- 894 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>`. 898 899.. code:: reST 900 901 .. sidebar:: KISS_ and readability_ 902 903 Instead of defining more and more roles, we at searx encourage our 904 contributors to follow principles like KISS_ and readability_. 905 906Generic admonition 907------------------ 908 909The generic :dudir:`admonition <admonitions>` needs a title: 910 911.. code:: reST 912 913 .. admonition:: generic admonition title 914 915 lorem ipsum .. 916 917 918.. admonition:: generic admonition title 919 920 lorem ipsum .. 921 922 923Specific admonitions 924-------------------- 925 926Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`, 927:dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and 928:dudir:`warning` . 929 930.. code:: reST 931 932 .. hint:: 933 934 lorem ipsum .. 935 936 .. note:: 937 938 lorem ipsum .. 939 940 .. warning:: 941 942 lorem ipsum .. 943 944 945.. hint:: 946 947 lorem ipsum .. 948 949.. note:: 950 951 lorem ipsum .. 952 953.. tip:: 954 955 lorem ipsum .. 956 957.. attention:: 958 959 lorem ipsum .. 960 961.. caution:: 962 963 lorem ipsum .. 964 965.. danger:: 966 967 lorem ipsum .. 968 969.. important:: 970 971 lorem ipsum .. 972 973.. error:: 974 975 lorem ipsum .. 976 977.. warning:: 978 979 lorem ipsum .. 980 981 982Tables 983====== 984 985.. sidebar:: Nested tables 986 987 Nested tables are ugly! Not all builder support nested tables, don't use 988 them! 989 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. 995 996 997.. sidebar:: List tables 998 999 For meaningful patch and diff use :ref:`reST flat table`. 1000 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: 1005 1006* `Emacs Table Mode`_ 1007* `Online Tables Generator`_ 1008 1009.. _reST simple table: 1010 1011Simple tables 1012------------- 1013 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: 1017 1018.. code:: reST 1019 1020 .. table:: foo gate truth table 1021 :widths: grid 1022 :align: left 1023 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 ====== ============= 1039 1040.. admonition:: Simple ASCII table 1041 :class: rst-example 1042 1043 .. table:: foo gate truth table 1044 :widths: grid 1045 :align: left 1046 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 ====== ============= 1062 1063 1064 1065.. _reST grid table: 1066 1067Grid tables 1068----------- 1069 1070:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*: 1071 1072.. code:: reST 1073 1074 .. table:: grid table example 1075 :widths: 1 1 5 1076 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 +------------+------------+-----------+ 1088 1089.. admonition:: ASCII grid table 1090 :class: rst-example 1091 1092 .. table:: grid table example 1093 :widths: 1 1 5 1094 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 +------------+------------+-----------+ 1106 1107 1108.. _reST flat table: 1109 1110flat-table 1111---------- 1112 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: 1116 1117column-span: ``cspan`` 1118 with the role ``cspan`` a cell can be extended through additional columns 1119 1120row-span: ``rspan`` 1121 with the role ``rspan`` a cell can be extended through additional rows 1122 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. 1128 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 1134 1135roles: 1136 :cspan: [int] additional columns (*morecols*) 1137 :rspan: [int] additional rows (*morerows*) 1138 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>`). 1143 1144.. code:: reST 1145 1146 .. flat-table:: ``flat-table`` example 1147 :header-rows: 2 1148 :stub-columns: 1 1149 :widths: 1 1 1 1 2 1150 1151 * - :rspan:`1` head / stub 1152 - :cspan:`3` head 1.1-4 1153 1154 * - head 2.1 1155 - head 2.2 1156 - head 2.3 1157 - head 2.4 1158 1159 * .. row body 1 / this is a comment 1160 1161 - row 1 1162 - :rspan:`2` cell 1-3.1 1163 - cell 1.2 1164 - cell 1.3 1165 - cell 1.4 1166 1167 * .. Comments and targets are allowed on *table-row* stage. 1168 .. _`row body 2`: 1169 1170 - row 2 1171 - cell 2.2 1172 - :rspan:`1` :cspan:`1` 1173 cell 2.3 with a span over 1174 1175 * col 3-4 & 1176 * row 2-3 1177 1178 * - row 3 1179 - cell 3.2 1180 1181 * - row 4 1182 - cell 4.1 1183 - cell 4.2 1184 - cell 4.3 1185 - cell 4.4 1186 1187 * - row 5 1188 - cell 5.1 with automatic span to rigth end 1189 1190 * - row 6 1191 - cell 6.1 1192 - .. 1193 1194 1195.. admonition:: List table 1196 :class: rst-example 1197 1198 .. flat-table:: ``flat-table`` example 1199 :header-rows: 2 1200 :stub-columns: 1 1201 :widths: 1 1 1 1 2 1202 1203 * - :rspan:`1` head / stub 1204 - :cspan:`3` head 1.1-4 1205 1206 * - head 2.1 1207 - head 2.2 1208 - head 2.3 1209 - head 2.4 1210 1211 * .. row body 1 / this is a comment 1212 1213 - row 1 1214 - :rspan:`2` cell 1-3.1 1215 - cell 1.2 1216 - cell 1.3 1217 - cell 1.4 1218 1219 * .. Comments and targets are allowed on *table-row* stage. 1220 .. _`row body 2`: 1221 1222 - row 2 1223 - cell 2.2 1224 - :rspan:`1` :cspan:`1` 1225 cell 2.3 with a span over 1226 1227 * col 3-4 & 1228 * row 2-3 1229 1230 * - row 3 1231 - cell 3.2 1232 1233 * - row 4 1234 - cell 4.1 1235 - cell 4.2 1236 - cell 4.3 1237 - cell 4.4 1238 1239 * - row 5 1240 - cell 5.1 with automatic span to rigth end 1241 1242 * - row 6 1243 - cell 6.1 1244 - .. 1245 1246 1247CSV table 1248--------- 1249 1250CSV table might be the choice if you want to include CSV-data from a outstanding 1251(build) process into your documentation. 1252 1253.. code:: reST 1254 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 1260 1261Content of file ``csv_table.txt``: 1262 1263.. literalinclude:: csv_table.txt 1264 1265.. admonition:: CSV table 1266 :class: rst-example 1267 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 1273 1274Templating 1275========== 1276 1277.. sidebar:: Build environment 1278 1279 All *generic-doc* tasks are running in the :ref:`build environment <make 1280 pyenv>`. 1281 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: 1287 1288.. literalinclude:: ../admin/engines.rst 1289 :language: reST 1290 :start-after: .. _configured engines: 1291 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``. 1295 1296.. code:: py 1297 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 }, 1307 } 1308 1309 1310Tabbed views 1311============ 1312 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 1317 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: 1322 1323.. literalinclude:: ../admin/buildhosts.rst 1324 :language: reST 1325 :start-after: .. SNIP sh lint requirements 1326 :end-before: .. SNAP sh lint requirements 1327 1328.. _math: 1329 1330Math equations 1331============== 1332 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 1336 1337.. sidebar:: About LaTeX 1338 1339 - `amsmath user guide`_ 1340 - Mathematics_ 1341 - :ref:`docs build` 1342 1343The input language for mathematics is LaTeX markup using the :ctan:`amsmath` 1344package. 1345 1346To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for 1347inline and directive :rst:dir:`.. math:: <math>` for block markup. 1348 1349.. code:: reST 1350 1351 In :math:numref:`schroedinger general` the time-dependent Schrödinger equation 1352 is shown. 1353 1354 .. math:: 1355 :label: schroedinger general 1356 1357 \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle = 1358 \hat{H} |\,\psi (t) \rangle. 1359 1360.. admonition:: LaTeX math equation 1361 :class: rst-example 1362 1363 In :math:numref:`schroedinger general` the time-dependent Schrödinger equation 1364 is shown. 1365 1366 .. math:: 1367 :label: schroedinger general 1368 1369 \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle = 1370 \hat{H} |\,\psi (t) \rangle. 1371 1372 1373The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac`` 1374(*displaystyle*) used in a inline markup or another fraction. 1375 1376.. code:: reST 1377 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}` 1380 1381.. admonition:: Line spacing 1382 :class: rst-example 1383 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. 1390 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. 1397 1398 1399.. _KISS: https://en.wikipedia.org/wiki/KISS_principle 1400 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 1434 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 1438
