@@ -97,14 +97,17 @@ Basic inline markup is done with asterisks and backquotes. If asterisks or
9797backquotes appear in running text and could be confused with inline markup
9898delimiters, they have to be escaped with a backslash (``\*pointer``).
9999
100−================================================ ==================== ========================
101−description rendered markup
102−================================================ ==================== ========================
103−one asterisk for emphasis *italics* ``*italics*``
104−two asterisks for strong emphasis **boldface** ``**boldface**``
105−backquotes for code samples and literals ``foo()`` ````foo()````
106−quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
107−================================================ ==================== ========================
100+.. table:: basic inline markup
101+ :widths: 4 3 7
102+
103+ ================================================ ==================== ========================
104+ description rendered markup
105+ ================================================ ==================== ========================
106+ one asterisk for emphasis *italics* ``*italics*``
107+ two asterisks for strong emphasis **boldface** ``**boldface**``
108+ backquotes for code samples and literals ``foo()`` ````foo()````
109+ quote asterisks or backquotes \*foo is a pointer ``\*foo is a pointer``
110+ ================================================ ==================== ========================
108111
109112.. _reST basic structure:
110113
@@ -269,27 +272,30 @@ Smart refs
269272With the power of sphinx.ext.extlinks_ and intersphinx_ referencing external
270273content becomes smart.
271274
272−========================== ================================== ====================================
273−refer ... rendered example markup
274−========================== ================================== ====================================
275−:rst:role:`rfc` :rfc:`822` ``:rfc:`822```
276−:rst:role:`pep` :pep:`8` ``:pep:`8```
277−sphinx.ext.extlinks_
278−--------------------------------------------------------------------------------------------------
279−project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances```
280−to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
281−files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
282−pull request :pull:`1756` ``:pull:`1756```
283−patch :patch:`af2cae6` ``:patch:`af2cae6```
284−PyPi package :pypi:`searx` ``:pypi:`searx```
285−manual page man :man:`bash` ``:man:`bash```
286−intersphinx_
287−--------------------------------------------------------------------------------------------------
288−external anchor :ref:`python:and` ``:ref:`python:and```
289−external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
290−python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
291−flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
292−========================== ================================== ====================================
275+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
276+ :widths: 4 3 7
277+
278+ ========================== ================================== ====================================
279+ refer ... rendered example markup
280+ ========================== ================================== ====================================
281+ :rst:role:`rfc` :rfc:`822` ``:rfc:`822```
282+ :rst:role:`pep` :pep:`8` ``:pep:`8```
283+ sphinx.ext.extlinks_
284+ --------------------------------------------------------------------------------------------------
285+ project's wiki article :wiki:`Searx-instances` ``:wiki:`Searx-instances```
286+ to docs public URL :docs:`dev/reST.html` ``:docs:`dev/reST.html```
287+ files & folders origin :origin:`docs/dev/reST.rst` ``:origin:`docs/dev/reST.rst```
288+ pull request :pull:`1756` ``:pull:`1756```
289+ patch :patch:`af2cae6` ``:patch:`af2cae6```
290+ PyPi package :pypi:`searx` ``:pypi:`searx```
291+ manual page man :man:`bash` ``:man:`bash```
292+ intersphinx_
293+ --------------------------------------------------------------------------------------------------
294+ external anchor :ref:`python:and` ``:ref:`python:and```
295+ external doc anchor :doc:`jinja:templates` ``:doc:`jinja:templates```
296+ python code object :py:obj:`datetime.datetime` ``:py:obj:`datetime.datetime```
297+ flask code object :py:obj:`flask.Flask` ``:py:obj:`flask.Flask```
298+ ========================== ================================== ====================================
293299
294300
295301Intersphinx is configured in :origin:`docs/conf.py`:
@@ -317,30 +323,43 @@ To list all anchors of the inventory (e.g. ``python``) use:
317323Roles
318324=====
319325
326+.. sidebar:: Further reading
327+
328+ - `Sphinx Roles`_
329+ - :doc:`sphinx:usage/restructuredtext/domains`
330+
331+
320332A *custom interpreted text role* (:duref:`ref <roles>`) is an inline piece of
321333explicit markup. It signifies that that the enclosed text should be interpreted
322−in a specific way. The general syntax is ``:rolename:`content```.
323−
324−========================== ================================== ====================================
325−role rendered example markup
326−========================== ================================== ====================================
327−:rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
328−:rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
329−:rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
330−:rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
331−:rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
332−:rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
333−:rst:role:`command` :command:`ls -la` ``:command:`ls -la```
334−:durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
335−:durole:`strong` :strong:`bold` ``:strong:`bold```
336−:durole:`literal` :literal:`foo()` ``:literal:`foo()```
337−:durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
338−:durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
339−:durole:`title-reference` :title:`Time` ``:title:`Time```
340−========================== ================================== ====================================
341−
342−Refer to `Sphinx Roles`_ for roles added by Sphinx.
334+in a specific way.
335+
336+The general markup is one of:
337+
338+.. code:: reST
343339
340+ :rolename:`ref-name`
341+ :rolename:`ref text <ref-name>`
342+
343+.. table:: smart refs with sphinx.ext.extlinks_ and intersphinx_
344+ :widths: 4 3 7
345+
346+ ========================== ================================== ====================================
347+ role rendered example markup
348+ ========================== ================================== ====================================
349+ :rst:role:`guilabel` :guilabel:`&Cancel` ``:guilabel:`&Cancel```
350+ :rst:role:`kbd` :kbd:`C-x C-f` ``:kbd:`C-x C-f```
351+ :rst:role:`menuselection` :menuselection:`Open --> File` ``:menuselection:`Open --> File```
352+ :rst:role:`download` :download:`this file <reST.rst>` ``:download:`this file <reST.rst>```
353+ :rst:role:`math` :math:`a^2 + b^2 = c^2` ``:math:`a^2 + b^2 = c^2```
354+ :rst:role:`ref` :ref:`svg image example` ``:ref:`svg image example```
355+ :rst:role:`command` :command:`ls -la` ``:command:`ls -la```
356+ :durole:`emphasis` :emphasis:`italic` ``:emphasis:`italic```
357+ :durole:`strong` :strong:`bold` ``:strong:`bold```
358+ :durole:`literal` :literal:`foo()` ``:literal:`foo()```
359+ :durole:`subscript` H\ :sub:`2`\ O ``H\ :sub:`2`\ O``
360+ :durole:`superscript` E = mc\ :sup:`2` ``E = mc\ :sup:`2```
361+ :durole:`title-reference` :title:`Time` ``:title:`Time```
362+ ========================== ================================== ====================================
344363
345364Figures & Images
346365================
@@ -420,7 +439,7 @@ Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
420439:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is
421440shown in figure :ref:`dot render example`:
422441
423−.. code-block:: rst
442+.. code:: reST
424443
425444 .. _dot render example:
426445
@@ -460,7 +479,7 @@ installed, you will see an vector image. If not, the raw markup is inserted as
460479
461480A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:
462481
463−.. code-block:: rst
482+.. code:: reST
464483
465484 .. _svg render example:
466485
@@ -768,8 +787,302 @@ Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attenti
768787 lorem ipsum ..
769788
770789
790+Tables
791+======
792+
793+.. sidebar:: Nested tables
794+
795+ Nested tables are ugly! Not all builder support nested tables, don't use
796+ them!
797+
798+ASCII-art tables like :ref:`reST simple table` and :ref:`reST grid table` might
799+be comfortable for readers of the text-files, but they have huge disadvantages
800+in the creation and modifying. First, they are hard to edit. Think about
801+adding a row or a column to a ASCII-art table or adding a paragraph in a cell,
802+it is a nightmare on big tables.
803+
804+
805+.. sidebar:: List tables
806+
807+ For meaningful patch and diff use :ref:`reST flat table`.
808+
809+Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a
810+cell generates a diff in which also changes are included, which are only
811+ascribable to the ASCII-art. Anyway, if you prefer ASCII-art for any reason,
812+here are some helpers:
813+
814+* `Emacs Table Mode`_
815+* `Online Tables Generator`_
816+
817+.. _reST simple table:
818+
819+Simple tables
820+-------------
821+
822+:duref:`Simple tables <simple-tables>` allow *colspan* but not *rowspan*. If
823+your table need some metadata (e.g. a title) you need to add the ``.. table::
824+directive`` :dudir:`(ref) <table>` in front and place the table in its body:
825+
826+.. code:: reST
827+
828+ .. table:: foo gate truth table
829+ :widths: grid
830+ :align: left
831+
832+ ====== ====== ======
833+ Inputs Output
834+ ------------- ------
835+ A B A or B
836+ ====== ====== ======
837+ False
838+ --------------------
839+ True
840+ --------------------
841+ True False True
842+ (foo)
843+ ------ ------ ------
844+ False True
845+ (foo)
846+ ====== =============
847+
848+.. admonition:: Simple ASCII table
849+ :class: rst-example
850+
851+ .. table:: foo gate truth table
852+ :widths: grid
853+ :align: left
854+
855+ ====== ====== ======
856+ Inputs Output
857+ ------------- ------
858+ A B A or B
859+ ====== ====== ======
860+ False
861+ --------------------
862+ True
863+ --------------------
864+ True False True
865+ (foo)
866+ ------ ------ ------
867+ False True
868+ (foo)
869+ ====== =============
870+
871+
872+
873+.. _reST grid table:
874+
875+Grid tables
876+-----------
877+
878+:duref:`Grid tables <grid-tables>` allow colspan *colspan* and *rowspan*:
879+
880+.. code:: reST
881+
882+ .. table:: grid table example
883+ :widths: 1 1 5
884+
885+ +------------+------------+-----------+
886+ | Header 1 | Header 2 | Header 3 |
887+ +============+============+===========+
888+ | body row 1 | column 2 | column 3 |
889+ +------------+------------+-----------+
890+ | body row 2 | Cells may span columns.|
891+ +------------+------------+-----------+
892+ | body row 3 | Cells may | - Cells |
893+ +------------+ span rows. | - contain |
894+ | body row 4 | | - blocks. |
895+ +------------+------------+-----------+
896+
897+.. admonition:: ASCII grid table
898+ :class: rst-example
899+
900+ .. table:: grid table example
901+ :widths: 1 1 5
902+
903+ +------------+------------+-----------+
904+ | Header 1 | Header 2 | Header 3 |
905+ +============+============+===========+
906+ | body row 1 | column 2 | column 3 |
907+ +------------+------------+-----------+
908+ | body row 2 | Cells may span columns.|
909+ +------------+------------+-----------+
910+ | body row 3 | Cells may | - Cells |
911+ +------------+ span rows. | - contain |
912+ | body row 4 | | - blocks. |
913+ +------------+------------+-----------+
914+
915+
916+.. _reST flat table:
917+
918+flat-table
919+----------
920+
921+The ``flat-table`` is a further developed variant of the :ref:`list tables
922+<linuxdoc:list-table-directives>`. It is a double-stage list similar to the
923+:dudir:`list-table` with some additional features:
924+
925+column-span: ``cspan``
926+ with the role ``cspan`` a cell can be extended through additional columns
927+
928+row-span: ``rspan``
929+ with the role ``rspan`` a cell can be extended through additional rows
930+
931+auto-span:
932+ spans rightmost cell of a table row over the missing cells on the right side
933+ of that table-row. With Option ``:fill-cells:`` this behavior can changed
934+ from *auto span* to *auto fill*, which automatically inserts (empty) cells
935+ instead of spanning the last cell.
936+
937+options:
938+ :header-rows: [int] count of header rows
939+ :stub-columns: [int] count of stub columns
940+ :widths: [[int] [int] ... ] widths of columns
941+ :fill-cells: instead of auto-span missing cells, insert missing cells
942+
943+roles:
944+ :cspan: [int] additional columns (*morecols*)
945+ :rspan: [int] additional rows (*morerows*)
946+
947+The example below shows how to use this markup. The first level of the staged
948+list is the *table-row*. In the *table-row* there is only one markup allowed,
949+the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
950+and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
951+
952+.. code:: reST
953+
954+ .. flat-table:: ``flat-table`` example
955+ :header-rows: 2
956+ :stub-columns: 1
957+ :widths: 1 1 1 1 2
958+
959+ * - :rspan:`1` head / stub
960+ - :cspan:`3` head 1.1-4
961+
962+ * - head 2.1
963+ - head 2.2
964+ - head 2.3
965+ - head 2.4
966+
967+ * .. row body 1 / this is a comment
968+
969+ - row 1
970+ - :rspan:`2` cell 1-3.1
971+ - cell 1.2
972+ - cell 1.3
973+ - cell 1.4
974+
975+ * .. Comments and targets are allowed on *table-row* stage.
976+ .. _`row body 2`:
977+
978+ - row 2
979+ - cell 2.2
980+ - :rspan:`1` :cspan:`1`
981+ cell 2.3 with a span over
982+
983+ * col 3-4 &
984+ * row 2-3
985+
986+ * - row 3
987+ - cell 3.2
988+
989+ * - row 4
990+ - cell 4.1
991+ - cell 4.2
992+ - cell 4.3
993+ - cell 4.4
994+
995+ * - row 5
996+ - cell 5.1 with automatic span to rigth end
997+
998+ * - row 6
999+ - cell 6.1
1000+ - ..
1001+
1002+
1003+.. admonition:: List table
1004+ :class: rst-example
1005+
1006+ .. flat-table:: ``flat-table`` example
1007+ :header-rows: 2
1008+ :stub-columns: 1
1009+ :widths: 1 1 1 1 2
1010+
1011+ * - :rspan:`1` head / stub
1012+ - :cspan:`3` head 1.1-4
1013+
1014+ * - head 2.1
1015+ - head 2.2
1016+ - head 2.3
1017+ - head 2.4
1018+
1019+ * .. row body 1 / this is a comment
1020+
1021+ - row 1
1022+ - :rspan:`2` cell 1-3.1
1023+ - cell 1.2
1024+ - cell 1.3
1025+ - cell 1.4
1026+
1027+ * .. Comments and targets are allowed on *table-row* stage.
1028+ .. _`row body 2`:
1029+
1030+ - row 2
1031+ - cell 2.2
1032+ - :rspan:`1` :cspan:`1`
1033+ cell 2.3 with a span over
1034+
1035+ * col 3-4 &
1036+ * row 2-3
1037+
1038+ * - row 3
1039+ - cell 3.2
1040+
1041+ * - row 4
1042+ - cell 4.1
1043+ - cell 4.2
1044+ - cell 4.3
1045+ - cell 4.4
1046+
1047+ * - row 5
1048+ - cell 5.1 with automatic span to rigth end
1049+
1050+ * - row 6
1051+ - cell 6.1
1052+ - ..
1053+
1054+
1055+CSV table
1056+---------
1057+
1058+CSV table might be the choice if you want to include CSV-data from a outstanding
1059+(build) process into your documentation.
1060+
1061+.. code:: reST
1062+
1063+ .. csv-table:: CSV table example
1064+ :header: .. , Column 1, Column 2
1065+ :widths: 2 5 5
1066+ :stub-columns: 1
1067+ :file: csv_table.txt
1068+
1069+Content of file ``csv_table.txt``:
1070+
1071+.. literalinclude:: csv_table.txt
1072+
1073+.. admonition:: CSV table
1074+ :class: rst-example
1075+
1076+ .. csv-table:: CSV table example
1077+ :header: .. , Column 1, Column 2
1078+ :widths: 3 5 5
1079+ :stub-columns: 1
1080+ :file: csv_table.txt
1081+
1082+
7711083
7721084.. _KISS: https://en.wikipedia.org/wiki/KISS_principle
1085+
7731086.. _readability: https://docs.python-guide.org/writing/style/
7741087.. _Sphinx-Primer:
7751088 http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
@@ -796,9 +1109,13 @@ Specific admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attenti
7961109.. _docutils: http://docutils.sourceforge.net/docs/index.html
7971110.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html
7981111.. _linuxdoc: https://return42.github.io/linuxdoc
1112+
7991113.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html
8001114.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html
8011115.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf
8021116.. _Graphviz: https://graphviz.gitlab.io
803−
8041117.. _ImageMagick: https://www.imagemagick.org
1118+
1119+.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
1120+.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables
1121+.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html