About tables¶

Note

The flat-table directive is the most diff friendly table markup, it is preferred in the Linux kernel tree.

Intro ¶

Internally, the docutils uses a representation according to the OASIS XML Exchange Table Model (same as DocBook). The OASIS Table Model gives a huge bandwidth of possibilities to form tables. This often seduce authors to force a specific layout. The misuse of tables in this manner is not recommended, it breaks the separation of presentation from content which most often ends in various problems in the range of output formats. Tables (and pre-formated text like source code listings) should be used advisedly. In a HTML viewer, the horizontal and vertical expansion is handled by a scrollbar. On print medias (paper / pdf) there is no scrollbar and automatically page-breaking a table or line-breaking a pre-formated text in the layout process ends mostly in unwanted results.

Hint

Tables and pre-formated text in itself violate the separation of presentation from content, but we will never be able to entirely renounce them. Use them with care, if your content should be rendered well, in the wide variation of output formats.

ASCII-art tables ¶

ASCII-art tables might be comfortable for readers of the text-files, but they have huge disadvantages in the creation and modifying. First, they are hard to edit. Think about adding a row or a column to a ASCII-art table or adding a paragraph in a cell, it is a nightmare on big tables. Second the diff of modifying ASCII-art tables is not meaningful, e.g. widening a cell generates a diff in which also changes are included, which are only ascribable to the ASCII-art (see also List table directives).

Simple tables ¶

simple tables allow colspan but not rowspan:

====== ====== ======
    Inputs    Output
------------- ------
A      B      A or B
====== ====== ======
False
--------------------
True
--------------------
True   False  True
------ ------ ------
False  True
====== =============

Rendered as:

Inputs		Output
A	B	A or B
False
True
True	False	True
False	True

Grid tables ¶

grid tables allow colspan colspan and rowspan:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

Rendered as:

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4	Cells may span rows.	Cells contain blocks.

List table directives ¶

The list table formats are double stage list, compared to the ASCII-art they might not be as comfortable for readers of the text-files. Their advantage is, that they are easy to create/modify and that the diff of a modification is much more meaningful, because it is limited to the modified content.

list-table ¶

The list-tables has no ability to colspan nor rowspan:

.. list-table:: list-table example
   :header-rows: 1
   :stub-columns: 1
   :class: my-class
   :name: my-list-table

   * - ..
     - head col 1
     - head col 2

   * - stub col row 1
     - column
     - column

   * - stub col row 2
     - column
     - column

   * - stub col row 3
     - column
     - column

Rendered in list-table example:

list-table example¶
	head col 1	head col 2
stub col row 1	column	column
stub col row 2	column	column
stub col row 3	column	column

flat-table ¶

The flat-table (FlatTable) is a double-stage list similar to the list-table with some additional features:

column-span: with the role cspan a cell can be extended through additional columns
row-span: with the role rspan a cell can be extended through additional rows
auto-span rightmost cell of a table row over the missing cells on the right side of that table-row. With Option :fill-cells: this behavior can changed from auto span to auto fill, which automatically inserts (empty) cells instead of spanning the last cell.

options:

header-rows:: [int] count of header rows
stub-columns:: [int] count of stub columns
widths:: [[int] [int] … ] widths of columns
fill-cells:: instead of auto-span missing cells, insert missing cells

roles:

cspan:: [int] additional columns (morecols)
rspan:: [int] additional rows (morerows)

The :rspan: and :cspan: are special reST-roles. These directives are used in the linuxdoc.rstFlatTable.ListTableBuilder and removed while the table is parsed. These reST-roles must not be in the translation:

#: ../index.rst:21
msgid ":rspan:`1` :cspan:`1` field 2.2 - 3.3"
msgstr "test (fr) field 2.2 - 3.3"

Most other reST-roles should be translated as-is:

#: ../index.rst:48
msgid ":math:`a^2 + b^2 = c^2`"
msgstr "test (fr) :math:`a^2 + b^2 = c^2`"

The example below shows how to use this markup. The first level of the staged list is the table-row. In the table-row there is only one markup allowed, the list of the cells in this table-row. Exception are comments ( .. ) and targets (e.g. a ref to row 2 of table’s body).

.. flat-table:: flat-table example
   :header-rows: 2
   :stub-columns: 1
   :widths: 1 1 1 1 2
   :class: my-class
   :name: my-flat-table

   * - :rspan:`1` head / stub
     - :cspan:`3` head 1.1-4

   * - head 2.1
     - head 2.2
     - head 2.3
     - head 2.4

   * .. row body 1 / this is a comment

     - row 1
     - :rspan:`2` cell 1-3.1
     - cell 1.2
     - cell 1.3
     - cell 1.4

   * .. Comments and targets are allowed on *table-row* stage.
     .. _`row body 2`:

     - row 2
     - cell 2.2
     - :rspan:`1` :cspan:`1`
       cell 2.3 with a span over

       * col 3-4 &
       * row 2-3

   * - row 3
     - cell 3.2

   * - row 4
     - cell 4.1
     - cell 4.2
     - cell 4.3
     - cell 4.4

   * - row 5
     - cell 5.1 with automatic span to rigth end

   * - row 6
     - cell 6.1
     - ..

Rendered in flat-table example:

flat-table example¶

head / stub

head 1.1-4

head 2.1

head 2.2

head 2.3

head 2.4

row 1

cell 1-3.1

cell 1.2

cell 1.3

cell 1.4

row 2

cell 2.2

cell 2.3 with a span over

col 3-4 &

row 2-3

row 3

cell 3.2

row 4

cell 4.1

cell 4.2

cell 4.3

cell 4.4

row 5

cell 5.1 with automatic span to rigth end

row 6

cell 6.1

CSV table ¶

CSV table might be the choice if you want to include CSV-data from a outstanding (build) process into your documentation.

.. csv-table:: csv-table example
   :header: , Header1, Header2
   :widths: 15, 10, 30
   :stub-columns: 1
   :file: csv_table.txt
   :class: my-class
   :name: my-csv-table

Content of file csv_table.txt:

stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
voluptua."
stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column
stub col row 1, column, column

Rendered in csv-table example:

csv-table example¶
	Header1	Header2
stub col row 1	column	loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
stub col row 1	At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.	column
stub col row 1	column	column

Nested Tables ¶

Nested tables are ugly, don’t use them! This part here is only to show what you should never do. They are ugly because they cause huge problems in many output formats and there is always no need for nested tables.

+-----------+----------------------------------------------------+
| W/NW cell | N/NE cell                                          |
|           +-------------+--------------------------+-----------+
|           | W/NW center | N/NE center              | E/SE cell |
|           |             +------------+-------------+           |
|           |             | +--------+ | E/SE center |           |
|           |             | | nested | |             |           |
|           |             | +--------+ |             |           |
|           |             | | table  | |             |           |
|           |             | +--------+ |             |           |
|           +-------------+------------+             |           |
|           | S/SE center              |             |           |
+-----------+--------------------------+-------------+           |
| S/SW cell                                          |           |
+----------------------------------------------------+-----------+

Rendered as: Not supported by all sphinx-builders, don’t use nested tables!!!

raw HTML tables ¶

If HTML is the only format you want to render, you could use a raw-import of a HTML table markup. But be aware, this breaks the separation of presentation from content. HTML-Tables are only rendered within a HTML output.

<div class="wy-table-responsive">
<table class="docutils">
  <thead>
    <tr style="font-weight: bold;">
      <td>Owner Module/Drivers</td>
      <td>Group</td>
      <td>Property Name</td>
      <td>Type</td>
      <td>Property Values</td>
      <td>Object attached</td>
      <td>Description/Restrictions</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="4">DRM</td>
      <td>Generic</td>
      <td>"rotation"</td>
      <td>BITMASK</td>
      <td>{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3,
        "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }</td>
      <td>CRTC, Plane</td>
      <td>rotate-(degrees) rotates the image by the specified amount in
       degrees in counter clockwise direction. reflect-x and reflect-y
       reflects the image along the specified axis prior to rotation</td>
    </tr>

    <tr>
      <td rowspan="3">Connector</td>
      <td>"EDID"</td>
      <td>BLOB | IMMUTABLE</td>
      <td>0</td>
      <td>Connector</td>
      <td>Contains id of edid blob ptr object.</td>
    </tr>

    <tr>
      <td>"DPMS"</td>
      <td>ENUM</td>
      <td>{ "On", "Standby", "Suspend", "Off" }</td>
      <td>Connector</td>
      <td>Contains DPMS operation mode value.</td>
    </tr>

    <tr>
      <td>"PATH"</td>
      <td>BLOB | IMMUTABLE</td>
      <td>0</td>
      <td>Connector</td>
      <td>Contains topology path to a connector.</td>
    </tr>
  </tbody>
</table>
</div>

Owner Module/Drivers	Group	Property Name	Type	Property Values	Object attached	Description/Restrictions
DRM	Generic	"rotation"	BITMASK	{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3, "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }	CRTC, Plane	rotate-(degrees) rotates the image by the specified amount in degrees in counter clockwise direction. reflect-x and reflect-y reflects the image along the specified axis prior to rotation
	Connector	"EDID"	BLOB \| IMMUTABLE	0	Connector	Contains id of edid blob ptr object.
		"DPMS"	ENUM	{ "On", "Standby", "Suspend", "Off" }	Connector	Contains DPMS operation mode value.
		"PATH"	BLOB \| IMMUTABLE	0	Connector	Contains topology path to a connector.