reST.rst 38 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438
  1. .. _reST primer:
  2. ===========
  3. reST primer
  4. ===========
  5. .. sidebar:: KISS_ and readability_
  6. Instead of defining more and more roles, we at searx encourage our
  7. contributors to follow principles like KISS_ and readability_.
  8. We at searx are using reStructuredText (aka reST_) markup for all kind of
  9. documentation, with the builders from the Sphinx_ project a HTML output is
  10. generated and deployed at :docs:`github.io <.>`. For build prerequisites read
  11. :ref:`docs build`.
  12. The source files of Searx's documentation are located at :origin:`docs`. Sphinx
  13. assumes source files to be encoded in UTF-8 by defaul. Run :ref:`make docs-live
  14. <make docs-live>` to build HTML while editing.
  15. .. sidebar:: Further reading
  16. - Sphinx-Primer_
  17. - `Sphinx markup constructs`_
  18. - reST_, docutils_, `docutils FAQ`_
  19. - Sphinx_, `sphinx-doc FAQ`_
  20. - `sphinx config`_, doctree_
  21. - `sphinx cross references`_
  22. - linuxdoc_
  23. - intersphinx_
  24. - sphinx-jinja_
  25. - `Sphinx's autodoc`_
  26. - `Sphinx's Python domain`_, `Sphinx's C domain`_
  27. - SVG_, ImageMagick_
  28. - DOT_, `Graphviz's dot`_, Graphviz_
  29. .. contents:: Contents
  30. :depth: 3
  31. :local:
  32. :backlinks: entry
  33. Sphinx_ and reST_ have their place in the python ecosystem. Over that reST is
  34. used in popular projects, e.g the Linux kernel documentation `[kernel doc]`_.
  35. .. _[kernel doc]: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
  36. .. sidebar:: Content matters
  37. The readability_ of the reST sources has its value, therefore we recommend to
  38. make sparse usage of reST markup / .. content matters!
  39. **reST** is a plaintext markup language, its markup is *mostly* intuitive and
  40. you will not need to learn much to produce well formed articles with. I use the
  41. word *mostly*: like everything in live, reST has its advantages and
  42. disadvantages, some markups feel a bit grumpy (especially if you are used to
  43. other plaintext markups).
  44. Soft skills
  45. ===========
  46. Before going any deeper into the markup let's face on some **soft skills** a
  47. trained author brings with, to reach a well feedback from readers:
  48. - Documentation is dedicated to an audience and answers questions from the
  49. audience point of view.
  50. - Don't detail things which are general knowledge from the audience point of
  51. view.
  52. - Limit the subject, use cross links for any further reading.
  53. To be more concrete what a *point of view* means. In the (:origin:`docs`)
  54. folder we have three sections (and the *blog* folder), each dedicate to a
  55. different group of audience.
  56. User's POV: :origin:`docs/user`
  57. A typical user knows about search engines and might have heard about
  58. meta crawlers and privacy.
  59. Admin's POV: :origin:`docs/admin`
  60. A typical Admin knows about setting up services on a linux system, but he does
  61. not know all the pros and cons of a searx setup.
  62. Developer's POV: :origin:`docs/dev`
  63. Depending on the readability_ of code, a typical developer is able to read and
  64. understand source code. Describe what a item aims to do (e.g. a function).
  65. If the chronological order matters, describe it. Name the *out-of-limits
  66. conditions* and all the side effects a external developer will not know.
  67. .. _reST inline markup:
  68. Basic inline markup
  69. ===================
  70. .. sidebar:: Inline markup
  71. - :ref:`reST roles`
  72. - :ref:`reST smart ref`
  73. Basic inline markup is done with asterisks and backquotes. If asterisks or
  74. backquotes appear in running text and could be confused with inline markup
  75. delimiters, they have to be escaped with a backslash (``\*pointer``).
  76. .. table:: basic inline markup
  77. :widths: 4 3 7
  78. ================================================ ==================== ========================
  79. description rendered markup
  80. ================================================ ==================== ========================
  81. one asterisk for emphasis *italics* ``*italics*``
  82. two asterisks for strong emphasis **boldface** ``**boldface**``
  83. backquotes for code samples and literals ``foo()`` ````foo()````
  84. quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
  85. ================================================ ==================== ========================
  86. .. _reST basic structure:
  87. Basic article structure
  88. =======================
  89. The basic structure of an article makes use of heading adornments to markup
  90. chapter, sections and subsections.
  91. .. _reST template:
  92. reST template
  93. -------------
  94. reST template for an simple article:
  95. .. code:: reST
  96. .. _doc refname:
  97. ==============
  98. Document title
  99. ==============
  100. Lorem ipsum dolor sit amet, consectetur adipisici elit .. Further read
  101. :ref:`chapter refname`.
  102. .. _chapter refname:
  103. Chapter
  104. =======
  105. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
  106. aliquid ex ea commodi consequat ...
  107. .. _section refname:
  108. Section
  109. -------
  110. lorem ..
  111. .. _subsection refname:
  112. Subsection
  113. ~~~~~~~~~~
  114. lorem ..
  115. Headings
  116. --------
  117. #. title - with overline for document title:
  118. .. code:: reST
  119. ==============
  120. Document title
  121. ==============
  122. #. chapter - with anchor named ``anchor name``:
  123. .. code:: reST
  124. .. _anchor name:
  125. Chapter
  126. =======
  127. #. section
  128. .. code:: reST
  129. Section
  130. -------
  131. #. subsection
  132. .. code:: reST
  133. Subsection
  134. ~~~~~~~~~~
  135. Anchors & Links
  136. ===============
  137. .. _reST anchor:
  138. Anchors
  139. -------
  140. .. _ref role:
  141. https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
  142. To refer a point in the documentation a anchor is needed. The :ref:`reST
  143. template <reST template>` shows an example where a chapter titled *"Chapters"*
  144. gets an anchor named ``chapter title``. Another example from *this* document,
  145. where the anchor named ``reST anchor``:
  146. .. code:: reST
  147. .. _reST anchor:
  148. Anchors
  149. -------
  150. To refer a point in the documentation a anchor is needed ...
  151. To refer anchors use the `ref role`_ markup:
  152. .. code:: reST
  153. Visit chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
  154. bar <reST anchor>`.
  155. .. admonition:: ``:ref:`` role
  156. :class: rst-example
  157. Visist chapter :ref:`reST anchor`. Or set hyperlink text manualy :ref:`foo
  158. bar <reST anchor>`.
  159. .. _reST ordinary ref:
  160. Link ordinary URL
  161. -----------------
  162. If you need to reference external URLs use *named* hyperlinks to maintain
  163. readability of reST sources. Here is a example taken from *this* article:
  164. .. code:: reST
  165. .. _Sphinx Field Lists:
  166. https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
  167. With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
  168. readable.
  169. And this shows the alternative (less readable) hyperlink markup `Sphinx Field
  170. Lists
  171. <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
  172. .. admonition:: Named hyperlink
  173. :class: rst-example
  174. With the *named* hyperlink `Sphinx Field Lists`_, the raw text is much more
  175. readable.
  176. And this shows the alternative (less readable) hyperlink markup `Sphinx Field
  177. Lists
  178. <https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html>`__.
  179. .. _reST smart ref:
  180. Smart refs
  181. ----------
  182. With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
  183. content becomes smart.
  184. .. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
  185. :widths: 4 3 7
  186. ========================== ================================== ====================================
  187. refer ... rendered example markup
  188. ========================== ================================== ====================================
  189. :rst:role:`rfc` :rfc:`822` ``:rfc:`822```
  190. :rst:role:`pep` :pep:`8` ``:pep:`8```
  191. sphinx.ext.extlinks_
  192. --------------------------------------------------------------------------------------------------
  193. project's wiki article :wiki:`Offline-engines` ``:wiki:`Offline-engines```
  194. to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
  195. files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
  196. pull request :pull:`1756` ``:pull:`1756```
  197. patch :patch:`af2cae6` ``:patch:`af2cae6```
  198. PyPi package :pypi:`searx` ``:pypi:`searx```
  199. manual page man :man:`bash` ``:man:`bash```
  200. intersphinx_
  201. --------------------------------------------------------------------------------------------------
  202. external anchor :ref:`python:and` ``:ref:`python:and```
  203. external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
  204. python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
  205. flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
  206. ========================== ================================== ====================================
  207. Intersphinx is configured in :origin:`docs/conf.py`:
  208. .. code:: python
  209. intersphinx_mapping = {
  210. "python": ("https://docs.python.org/3/", None),
  211. "flask": ("https://flask.palletsprojects.com/", None),
  212. "jinja": ("https://jinja.palletsprojects.com/", None),
  213. "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),
  214. "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),
  215. }
  216. To list all anchors of the inventory (e.g. ``python``) use:
  217. .. code:: sh
  218. $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
  219. ...
  220. $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
  221. ...
  222. Literal blocks
  223. ==============
  224. The simplest form of :duref:`literal-blocks` is a indented block introduced by
  225. two colons (``::``). For highlighting use :dudir:`highlight` or :ref:`reST
  226. code` directive. To include literals from external files use
  227. :rst:dir:`literalinclude` or :ref:`kernel-include <kernel-include-directive>`
  228. directive (latter one expands environment variables in the path name).
  229. .. _reST literal:
  230. ``::``
  231. ------
  232. .. code:: reST
  233. ::
  234. Literal block
  235. Lorem ipsum dolor::
  236. Literal block
  237. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
  238. eirmod tempor invidunt ut labore ::
  239. Literal block
  240. .. admonition:: Literal block
  241. :class: rst-example
  242. ::
  243. Literal block
  244. Lorem ipsum dolor::
  245. Literal block
  246. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
  247. eirmod tempor invidunt ut labore ::
  248. Literal block
  249. .. _reST code:
  250. ``code-block``
  251. --------------
  252. .. _pygments: https://pygments.org/languages/
  253. .. sidebar:: Syntax highlighting
  254. is handled by pygments_.
  255. The :rst:dir:`code-block` directive is a variant of the :dudir:`code` directive
  256. with additional options. To learn more about code literals visit
  257. :ref:`sphinx:code-examples`.
  258. .. code-block:: reST
  259. The URL ``/stats`` handle is shown in :ref:`stats-handle`
  260. .. code-block:: Python
  261. :caption: python code block
  262. :name: stats-handle
  263. @app.route('/stats', methods=['GET'])
  264. def stats():
  265. """Render engine statistics page."""
  266. stats = get_engines_stats()
  267. return render(
  268. 'stats.html'
  269. , stats = stats )
  270. .. code-block:: reST
  271. .. admonition:: Code block
  272. :class: rst-example
  273. The URL ``/stats`` handle is shown in :ref:`stats-handle`
  274. .. code-block:: Python
  275. :caption: python code block
  276. :name: stats-handle
  277. @app.route('/stats', methods=['GET'])
  278. def stats():
  279. """Render engine statistics page."""
  280. stats = get_engines_stats()
  281. return render(
  282. 'stats.html'
  283. , stats = stats )
  284. Unicode substitution
  285. ====================
  286. The :dudir:`unicode directive <unicode-character-codes>` converts Unicode
  287. character codes (numerical values) to characters. This directive can only be
  288. used within a substitution definition.
  289. .. code-block:: reST
  290. .. |copy| unicode:: 0xA9 .. copyright sign
  291. .. |(TM)| unicode:: U+2122
  292. Trademark |(TM)| and copyright |copy| glyphs.
  293. .. admonition:: Unicode
  294. :class: rst-example
  295. .. |copy| unicode:: 0xA9 .. copyright sign
  296. .. |(TM)| unicode:: U+2122
  297. Trademark |(TM)| and copyright |copy| glyphs.
  298. .. _reST roles:
  299. Roles
  300. =====
  301. .. sidebar:: Further reading
  302. - `Sphinx Roles`_
  303. - :doc:`sphinx:usage/restructuredtext/domains`
  304. A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
  305. explicit markup. It signifies that that the enclosed text should be interpreted
  306. in a specific way.
  307. The general markup is one of:
  308. .. code:: reST
  309. :rolename:`ref-name`
  310. :rolename:`ref text <ref-name>`
  311. .. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
  312. :widths: 4 3 7
  313. ========================== ================================== ====================================
  314. role rendered example markup
  315. ========================== ================================== ====================================
  316. :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
  317. :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
  318. :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
  319. :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
  320. math_ :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
  321. :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
  322. :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
  323. :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
  324. :durole:`strong` :strong:`bold` ``:strong:`bold```
  325. :durole:`literal` :literal:`foo()` ``:literal:`foo()```
  326. :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
  327. :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
  328. :durole:`title-reference` :title:`Time` ``:title:`Time```
  329. ========================== ================================== ====================================
  330. Figures & Images
  331. ================
  332. .. sidebar:: Image processing
  333. With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process
  334. is flexible. To get best results in the generated output format, install
  335. ImageMagick_ and Graphviz_.
  336. Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scaleable here means;
  337. scaleable in sense of the build process. Normally in absence of a converter
  338. tool, the build process will break. From the authors POV it’s annoying to care
  339. about the build process when handling with images, especially since he has no
  340. access to the build process. With :ref:`linuxdoc:kfigure` the build process
  341. continues and scales output quality in dependence of installed image processors.
  342. If you want to add an image, you should use the ``kernel-figure`` (inheritance
  343. of :dudir:`figure`) and ``kernel-image`` (inheritance of :dudir:`image`)
  344. directives. E.g. to insert a figure with a scaleable image format use SVG
  345. (:ref:`svg image example`):
  346. .. code:: reST
  347. .. _svg image example:
  348. .. kernel-figure:: svg_image.svg
  349. :alt: SVG image example
  350. Simple SVG image
  351. To refer the figure, a caption block is needed: :ref:`svg image example`.
  352. .. _svg image example:
  353. .. kernel-figure:: svg_image.svg
  354. :alt: SVG image example
  355. Simple SVG image.
  356. To refer the figure, a caption block is needed: :ref:`svg image example`.
  357. DOT files (aka Graphviz)
  358. ------------------------
  359. With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is
  360. given.
  361. - `Graphviz's dot`_
  362. - DOT_
  363. - Graphviz_
  364. A simple example is shown in :ref:`dot file example`:
  365. .. code:: reST
  366. .. _dot file example:
  367. .. kernel-figure:: hello.dot
  368. :alt: hello world
  369. DOT's hello world example
  370. .. admonition:: hello.dot
  371. :class: rst-example
  372. .. _dot file example:
  373. .. kernel-figure:: hello.dot
  374. :alt: hello world
  375. DOT's hello world example
  376. ``kernel-render`` DOT
  377. ---------------------
  378. Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
  379. :ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
  380. shown in figure :ref:`dot render example`:
  381. .. code:: reST
  382. .. _dot render example:
  383. .. kernel-render:: DOT
  384. :alt: digraph
  385. :caption: Embedded DOT (Graphviz) code
  386. digraph foo {
  387. "bar" -> "baz";
  388. }
  389. Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
  390. render example`.
  391. Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is
  392. installed, you will see an vector image. If not, the raw markup is inserted as
  393. *literal-block*.
  394. .. admonition:: kernel-render DOT
  395. :class: rst-example
  396. .. _dot render example:
  397. .. kernel-render:: DOT
  398. :alt: digraph
  399. :caption: Embedded DOT (Graphviz) code
  400. digraph foo {
  401. "bar" -> "baz";
  402. }
  403. Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot
  404. render example`.
  405. ``kernel-render`` SVG
  406. ---------------------
  407. A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
  408. .. code:: reST
  409. .. _svg render example:
  410. .. kernel-render:: SVG
  411. :caption: Embedded **SVG** markup
  412. :alt: so-nw-arrow
  413. ..
  414. .. code:: xml
  415. <?xml version="1.0" encoding="UTF-8"?>
  416. <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
  417. baseProfile="full" width="70px" height="40px"
  418. viewBox="0 0 700 400"
  419. >
  420. <line x1="180" y1="370"
  421. x2="500" y2="50"
  422. stroke="black" stroke-width="15px"
  423. />
  424. <polygon points="585 0 525 25 585 50"
  425. transform="rotate(135 525 25)"
  426. />
  427. </svg>
  428. .. admonition:: kernel-render SVG
  429. :class: rst-example
  430. .. _svg render example:
  431. .. kernel-render:: SVG
  432. :caption: Embedded **SVG** markup
  433. :alt: so-nw-arrow
  434. <?xml version="1.0" encoding="UTF-8"?>
  435. <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
  436. baseProfile="full" width="70px" height="40px"
  437. viewBox="0 0 700 400"
  438. >
  439. <line x1="180" y1="370"
  440. x2="500" y2="50"
  441. stroke="black" stroke-width="15px"
  442. />
  443. <polygon points="585 0 525 25 585 50"
  444. transform="rotate(135 525 25)"
  445. />
  446. </svg>
  447. .. _reST lists:
  448. List markups
  449. ============
  450. Bullet list
  451. -----------
  452. List markup (:duref:`ref <bullet-lists>`) is simple:
  453. .. code:: reST
  454. - This is a bulleted list.
  455. 1. Nested lists are possible, but be aware that they must be separated from
  456. the parent list items by blank line
  457. 2. Second item of nested list
  458. - It has two items, the second
  459. item uses two lines.
  460. #. This is a numbered list.
  461. #. It has two items too.
  462. .. admonition:: bullet list
  463. :class: rst-example
  464. - This is a bulleted list.
  465. 1. Nested lists are possible, but be aware that they must be separated from
  466. the parent list items by blank line
  467. 2. Second item of nested list
  468. - It has two items, the second
  469. item uses two lines.
  470. #. This is a numbered list.
  471. #. It has two items too.
  472. Horizontal list
  473. ---------------
  474. The :rst:dir:`.. hlist:: <hlist>` transforms a bullet list into a more compact
  475. list.
  476. .. code:: reST
  477. .. hlist::
  478. - first list item
  479. - second list item
  480. - third list item
  481. ...
  482. .. admonition:: hlist
  483. :class: rst-example
  484. .. hlist::
  485. - first list item
  486. - second list item
  487. - third list item
  488. - next list item
  489. - next list item xxxx
  490. - next list item yyyy
  491. - next list item zzzz
  492. Definition list
  493. ---------------
  494. .. sidebar:: Note ..
  495. - the term cannot have more than one line of text
  496. - there is **no blank line between term and definition block** // this
  497. distinguishes definition lists (:duref:`ref <definition-lists>`) from block
  498. quotes (:duref:`ref <block-quotes>`).
  499. Each definition list (:duref:`ref <definition-lists>`) item contains a term,
  500. optional classifiers and a definition. A term is a simple one-line word or
  501. phrase. Optional classifiers may follow the term on the same line, each after
  502. an inline ' : ' (**space, colon, space**). A definition is a block indented
  503. relative to the term, and may contain multiple paragraphs and other body
  504. elements. There may be no blank line between a term line and a definition block
  505. (*this distinguishes definition lists from block quotes*). Blank lines are
  506. required before the first and after the last definition list item, but are
  507. optional in-between.
  508. Definition lists are created as follows:
  509. .. code:: reST
  510. term 1 (up to a line of text)
  511. Definition 1.
  512. See the typo : this line is not a term!
  513. And this is not term's definition. **There is a blank line** in between
  514. the line above and this paragraph. That's why this paragraph is taken as
  515. **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
  516. term 2
  517. Definition 2, paragraph 1.
  518. Definition 2, paragraph 2.
  519. term 3 : classifier
  520. Definition 3.
  521. term 4 : classifier one : classifier two
  522. Definition 4.
  523. .. admonition:: definition list
  524. :class: rst-example
  525. term 1 (up to a line of text)
  526. Definition 1.
  527. See the typo : this line is not a term!
  528. And this is not term's definition. **There is a blank line** in between
  529. the line above and this paragraph. That's why this paragraph is taken as
  530. **block quote** (:duref:`ref <block-quotes>`) and not as term's definition!
  531. term 2
  532. Definition 2, paragraph 1.
  533. Definition 2, paragraph 2.
  534. term 3 : classifier
  535. Definition 3.
  536. term 4 : classifier one : classifier two
  537. Quoted paragraphs
  538. -----------------
  539. Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
  540. them more than the surrounding paragraphs. Line blocks (:duref:`ref
  541. <line-blocks>`) are a way of preserving line breaks:
  542. .. code:: reST
  543. normal paragraph ...
  544. lorem ipsum.
  545. Quoted paragraph ...
  546. lorem ipsum.
  547. | These lines are
  548. | broken exactly like in
  549. | the source file.
  550. .. admonition:: Quoted paragraph and line block
  551. :class: rst-example
  552. normal paragraph ...
  553. lorem ipsum.
  554. Quoted paragraph ...
  555. lorem ipsum.
  556. | These lines are
  557. | broken exactly like in
  558. | the source file.
  559. .. _reST field list:
  560. Field Lists
  561. -----------
  562. .. _Sphinx Field Lists:
  563. https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
  564. .. sidebar:: bibliographic fields
  565. First lines fields are bibliographic fields, see `Sphinx Field Lists`_.
  566. Field lists are used as part of an extension syntax, such as options for
  567. directives, or database-like records meant for further processing. Field lists
  568. are mappings from field names to field bodies. They marked up like this:
  569. .. code:: reST
  570. :fieldname: Field content
  571. :foo: first paragraph in field foo
  572. second paragraph in field foo
  573. :bar: Field content
  574. .. admonition:: Field List
  575. :class: rst-example
  576. :fieldname: Field content
  577. :foo: first paragraph in field foo
  578. second paragraph in field foo
  579. :bar: Field content
  580. They are commonly used in Python documentation:
  581. .. code:: python
  582. def my_function(my_arg, my_other_arg):
  583. """A function just for me.
  584. :param my_arg: The first of my arguments.
  585. :param my_other_arg: The second of my arguments.
  586. :returns: A message (just for me, of course).
  587. """
  588. Further list blocks
  589. -------------------
  590. - field lists (:duref:`ref <field-lists>`, with caveats noted in
  591. :ref:`reST field list`)
  592. - option lists (:duref:`ref <option-lists>`)
  593. - quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
  594. - doctest blocks (:duref:`ref <doctest-blocks>`)
  595. Admonitions
  596. ===========
  597. Sidebar
  598. -------
  599. Sidebar is an eye catcher, often used for admonitions pointing further stuff or
  600. site effects. Here is the source of the sidebar :ref:`on top of this page <reST
  601. primer>`.
  602. .. code:: reST
  603. .. sidebar:: KISS_ and readability_
  604. Instead of defining more and more roles, we at searx encourage our
  605. contributors to follow principles like KISS_ and readability_.
  606. Generic admonition
  607. ------------------
  608. The generic :dudir:`admonition <admonitions>` needs a title:
  609. .. code:: reST
  610. .. admonition:: generic admonition title
  611. lorem ipsum ..
  612. .. admonition:: generic admonition title
  613. lorem ipsum ..
  614. Specific admonitions
  615. --------------------
  616. Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,
  617. :dudir:`caution`, :dudir:`danger`, :dudir:`error`, , :dudir:`important`, and
  618. :dudir:`warning` .
  619. .. code:: reST
  620. .. hint::
  621. lorem ipsum ..
  622. .. note::
  623. lorem ipsum ..
  624. .. warning::
  625. lorem ipsum ..
  626. .. hint::
  627. lorem ipsum ..
  628. .. note::
  629. lorem ipsum ..
  630. .. tip::
  631. lorem ipsum ..
  632. .. attention::
  633. lorem ipsum ..
  634. .. caution::
  635. lorem ipsum ..
  636. .. danger::
  637. lorem ipsum ..
  638. .. important::
  639. lorem ipsum ..
  640. .. error::
  641. lorem ipsum ..
  642. .. warning::
  643. lorem ipsum ..
  644. Tables
  645. ======
  646. .. sidebar:: Nested tables
  647. Nested tables are ugly! Not all builder support nested tables, don't use
  648. them!
  649. ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
  650. be comfortable for readers of the text-files, but they have huge disadvantages
  651. in the creation and modifying. First, they are hard to edit. Think about
  652. adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
  653. it is a nightmare on big tables.
  654. .. sidebar:: List tables
  655. For meaningful patch and diff use :ref:`reST flat table`.
  656. Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
  657. cell generates a diff in which also changes are included, which are only
  658. ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
  659. here are some helpers:
  660. * `Emacs Table Mode`_
  661. * `Online Tables Generator`_
  662. .. _reST simple table:
  663. Simple tables
  664. -------------
  665. :duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
  666. your table need some metadata (e.g. a title) you need to add the ``.. table::
  667. directive`` :dudir:`(ref) <table>` in front and place the table in its body:
  668. .. code:: reST
  669. .. table:: foo gate truth table
  670. :widths: grid
  671. :align: left
  672. ====== ====== ======
  673. Inputs Output
  674. ------------- ------
  675. A B A or B
  676. ====== ====== ======
  677. False
  678. --------------------
  679. True
  680. --------------------
  681. True False True
  682. (foo)
  683. ------ ------ ------
  684. False True
  685. (foo)
  686. ====== =============
  687. .. admonition:: Simple ASCII table
  688. :class: rst-example
  689. .. table:: foo gate truth table
  690. :widths: grid
  691. :align: left
  692. ====== ====== ======
  693. Inputs Output
  694. ------------- ------
  695. A B A or B
  696. ====== ====== ======
  697. False
  698. --------------------
  699. True
  700. --------------------
  701. True False True
  702. (foo)
  703. ------ ------ ------
  704. False True
  705. (foo)
  706. ====== =============
  707. .. _reST grid table:
  708. Grid tables
  709. -----------
  710. :duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
  711. .. code:: reST
  712. .. table:: grid table example
  713. :widths: 1 1 5
  714. +------------+------------+-----------+
  715. | Header 1 | Header 2 | Header 3 |
  716. +============+============+===========+
  717. | body row 1 | column 2 | column 3 |
  718. +------------+------------+-----------+
  719. | body row 2 | Cells may span columns.|
  720. +------------+------------+-----------+
  721. | body row 3 | Cells may | - Cells |
  722. +------------+ span rows. | - contain |
  723. | body row 4 | | - blocks. |
  724. +------------+------------+-----------+
  725. .. admonition:: ASCII grid table
  726. :class: rst-example
  727. .. table:: grid table example
  728. :widths: 1 1 5
  729. +------------+------------+-----------+
  730. | Header 1 | Header 2 | Header 3 |
  731. +============+============+===========+
  732. | body row 1 | column 2 | column 3 |
  733. +------------+------------+-----------+
  734. | body row 2 | Cells may span columns.|
  735. +------------+------------+-----------+
  736. | body row 3 | Cells may | - Cells |
  737. +------------+ span rows. | - contain |
  738. | body row 4 | | - blocks. |
  739. +------------+------------+-----------+
  740. .. _reST flat table:
  741. flat-table
  742. ----------
  743. The ``flat-table`` is a further developed variant of the :ref:`list tables
  744. <linuxdoc:list-table-directives>`. It is a double-stage list similar to the
  745. :dudir:`list-table` with some additional features:
  746. column-span: ``cspan``
  747. with the role ``cspan`` a cell can be extended through additional columns
  748. row-span: ``rspan``
  749. with the role ``rspan`` a cell can be extended through additional rows
  750. auto-span:
  751. spans rightmost cell of a table row over the missing cells on the right side
  752. of that table-row. With Option ``:fill-cells:`` this behavior can changed
  753. from *auto span* to *auto fill*, which automatically inserts (empty) cells
  754. instead of spanning the last cell.
  755. options:
  756. :header-rows: [int] count of header rows
  757. :stub-columns: [int] count of stub columns
  758. :widths: [[int] [int] ... ] widths of columns
  759. :fill-cells: instead of auto-span missing cells, insert missing cells
  760. roles:
  761. :cspan: [int] additional columns (*morecols*)
  762. :rspan: [int] additional rows (*morerows*)
  763. The example below shows how to use this markup. The first level of the staged
  764. list is the *table-row*. In the *table-row* there is only one markup allowed,
  765. the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
  766. and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
  767. .. code:: reST
  768. .. flat-table:: ``flat-table`` example
  769. :header-rows: 2
  770. :stub-columns: 1
  771. :widths: 1 1 1 1 2
  772. * - :rspan:`1` head / stub
  773. - :cspan:`3` head 1.1-4
  774. * - head 2.1
  775. - head 2.2
  776. - head 2.3
  777. - head 2.4
  778. * .. row body 1 / this is a comment
  779. - row 1
  780. - :rspan:`2` cell 1-3.1
  781. - cell 1.2
  782. - cell 1.3
  783. - cell 1.4
  784. * .. Comments and targets are allowed on *table-row* stage.
  785. .. _`row body 2`:
  786. - row 2
  787. - cell 2.2
  788. - :rspan:`1` :cspan:`1`
  789. cell 2.3 with a span over
  790. * col 3-4 &
  791. * row 2-3
  792. * - row 3
  793. - cell 3.2
  794. * - row 4
  795. - cell 4.1
  796. - cell 4.2
  797. - cell 4.3
  798. - cell 4.4
  799. * - row 5
  800. - cell 5.1 with automatic span to rigth end
  801. * - row 6
  802. - cell 6.1
  803. - ..
  804. .. admonition:: List table
  805. :class: rst-example
  806. .. flat-table:: ``flat-table`` example
  807. :header-rows: 2
  808. :stub-columns: 1
  809. :widths: 1 1 1 1 2
  810. * - :rspan:`1` head / stub
  811. - :cspan:`3` head 1.1-4
  812. * - head 2.1
  813. - head 2.2
  814. - head 2.3
  815. - head 2.4
  816. * .. row body 1 / this is a comment
  817. - row 1
  818. - :rspan:`2` cell 1-3.1
  819. - cell 1.2
  820. - cell 1.3
  821. - cell 1.4
  822. * .. Comments and targets are allowed on *table-row* stage.
  823. .. _`row body 2`:
  824. - row 2
  825. - cell 2.2
  826. - :rspan:`1` :cspan:`1`
  827. cell 2.3 with a span over
  828. * col 3-4 &
  829. * row 2-3
  830. * - row 3
  831. - cell 3.2
  832. * - row 4
  833. - cell 4.1
  834. - cell 4.2
  835. - cell 4.3
  836. - cell 4.4
  837. * - row 5
  838. - cell 5.1 with automatic span to rigth end
  839. * - row 6
  840. - cell 6.1
  841. - ..
  842. CSV table
  843. ---------
  844. CSV table might be the choice if you want to include CSV-data from a outstanding
  845. (build) process into your documentation.
  846. .. code:: reST
  847. .. csv-table:: CSV table example
  848. :header: .. , Column 1, Column 2
  849. :widths: 2 5 5
  850. :stub-columns: 1
  851. :file: csv_table.txt
  852. Content of file ``csv_table.txt``:
  853. .. literalinclude:: csv_table.txt
  854. .. admonition:: CSV table
  855. :class: rst-example
  856. .. csv-table:: CSV table example
  857. :header: .. , Column 1, Column 2
  858. :widths: 3 5 5
  859. :stub-columns: 1
  860. :file: csv_table.txt
  861. Templating
  862. ==========
  863. .. sidebar:: Build environment
  864. All *generic-doc* tasks are running in the :ref:`build environment <make
  865. pyenv>`.
  866. Templating is suitable for documentation which is created generic at the build
  867. time. The sphinx-jinja_ extension evaluates jinja_ templates in the :ref:`build
  868. environment <make pyenv>` (with searx modules installed). We use this e.g. to
  869. build chapter: :ref:`engines generic`. Below the jinja directive from the
  870. :origin:`docs/admin/engines.rst` is shown:
  871. .. literalinclude:: ../admin/engines.rst
  872. :language: reST
  873. :start-after: .. _configured engines:
  874. The context for the template is selected in the line ``.. jinja:: searx``. In
  875. sphinx's build configuration (:origin:`docs/conf.py`) the ``searx`` context
  876. contains the ``engines`` and ``plugins``.
  877. .. code:: py
  878. import searx.search
  879. import searx.engines
  880. import searx.plugins
  881. searx.search.initialize()
  882. jinja_contexts = {
  883. 'searx': {
  884. 'engines': searx.engines.engines,
  885. 'plugins': searx.plugins.plugins
  886. },
  887. }
  888. Tabbed views
  889. ============
  890. .. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
  891. .. _basic-tabs: https://github.com/djungelorm/sphinx-tabs#basic-tabs
  892. .. _group-tabs: https://github.com/djungelorm/sphinx-tabs#group-tabs
  893. .. _code-tabs: https://github.com/djungelorm/sphinx-tabs#code-tabs
  894. With `sphinx-tabs`_ extension we have *tabbed views*. To provide installation
  895. instructions with one tab per distribution we use the `group-tabs`_ directive,
  896. others are basic-tabs_ and code-tabs_. Below a *group-tab* example from
  897. :ref:`docs build` is shown:
  898. .. literalinclude:: ../admin/buildhosts.rst
  899. :language: reST
  900. :start-after: .. SNIP sh lint requirements
  901. :end-before: .. SNAP sh lint requirements
  902. .. _math:
  903. Math equations
  904. ==============
  905. .. _Mathematics: https://en.wikibooks.org/wiki/LaTeX/Mathematics
  906. .. _amsmath user guide:
  907. http://vesta.informatik.rwth-aachen.de/ftp/pub/mirror/ctan/macros/latex/required/amsmath/amsldoc.pdf
  908. .. sidebar:: About LaTeX
  909. - `amsmath user guide`_
  910. - Mathematics_
  911. - :ref:`docs build`
  912. The input language for mathematics is LaTeX markup using the :ctan:`amsmath`
  913. package.
  914. To embed LaTeX markup in reST documents, use role :rst:role:`:math: <math>` for
  915. inline and directive :rst:dir:`.. math:: <math>` for block markup.
  916. .. code:: reST
  917. In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
  918. is shown.
  919. .. math::
  920. :label: schroedinger general
  921. \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
  922. \hat{H} |\,\psi (t) \rangle.
  923. .. admonition:: LaTeX math equation
  924. :class: rst-example
  925. In :math:numref:`schroedinger general` the time-dependent Schrödinger equation
  926. is shown.
  927. .. math::
  928. :label: schroedinger general
  929. \mathrm{i}\hbar\dfrac{\partial}{\partial t} |\,\psi (t) \rangle =
  930. \hat{H} |\,\psi (t) \rangle.
  931. The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac``
  932. (*displaystyle*) used in a inline markup or another fraction.
  933. .. code:: reST
  934. ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
  935. ``\dfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
  936. .. admonition:: Line spacing
  937. :class: rst-example
  938. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
  939. eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
  940. voluptua. ...
  941. ``\tfrac`` **inline example** :math:`\tfrac{\tfrac{1}{x}+\tfrac{1}{y}}{y-z}`
  942. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
  943. gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
  944. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
  945. eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
  946. voluptua. ...
  947. ``\tfrac`` **inline example** :math:`\dfrac{\dfrac{1}{x}+\dfrac{1}{y}}{y-z}`
  948. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
  949. gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
  950. .. _KISS: https://en.wikipedia.org/wiki/KISS_principle
  951. .. _readability: https://docs.python-guide.org/writing/style/
  952. .. _Sphinx-Primer:
  953. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
  954. .. _reST: https://docutils.sourceforge.io/rst.html
  955. .. _Sphinx Roles:
  956. https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
  957. .. _Sphinx: https://www.sphinx-doc.org
  958. .. _`sphinx-doc FAQ`: https://www.sphinx-doc.org/en/stable/faq.html
  959. .. _Sphinx markup constructs:
  960. https://www.sphinx-doc.org/en/stable/markup/index.html
  961. .. _`sphinx cross references`:
  962. https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
  963. .. _sphinx.ext.extlinks:
  964. https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
  965. .. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
  966. .. _sphinx config: https://www.sphinx-doc.org/en/stable/config.html
  967. .. _Sphinx's autodoc: https://www.sphinx-doc.org/en/stable/ext/autodoc.html
  968. .. _Sphinx's Python domain:
  969. https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
  970. .. _Sphinx's C domain:
  971. https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
  972. .. _doctree:
  973. https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases
  974. .. _docutils: http://docutils.sourceforge.net/docs/index.html
  975. .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
  976. .. _linuxdoc: https://return42.github.io/linuxdoc
  977. .. _jinja: https://jinja.palletsprojects.com/
  978. .. _sphinx-jinja: https://github.com/tardyp/sphinx-jinja
  979. .. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
  980. .. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
  981. .. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
  982. .. _Graphviz: https://graphviz.gitlab.io
  983. .. _ImageMagick: https://www.imagemagick.org
  984. .. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
  985. .. _`Online Tables Generator`: https://www.tablesgenerator.com/text_tables
  986. .. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html