.. _rest_tables:

Tables
******

Tables must only be used for information that is either too numerous or too
related for a list to be appropriate. The general rule of thumb is that the
minimal size of a table is a 2x2 not counting the table header. The
use of ReST makes table size much more important. Tables are difficult to
do properly in ReST following the line length restrictions. If you plan on
adding content in form of a table consider transforming it into a list
before you embark on creating a table. Follow these general guidelines:

* Use tables sparingly.

* Keep the 72-78 characters line length in mind.

* Indent the contents correctly. This allows the content to be read even if
  it is not rendered.

* Only create a table if the body of the table is larger than 6, that means
  either 2x3 or 3x2.


ReST supports two types of tables: simple and grid tables. Single tables are
only suited for very short content since they only allow cells with a single
line. Grid tables support multi-lined cells and offer many layout options.

Use simple tables only to create a matrix of terms, for example:

============ =========== ===========
Number       Name        Color
============ =========== ===========
1            Door        Brown
2            Floors      Gray
3            Ceilings    Blue
============ =========== ===========

Use the following template to create a simple table.

.. code-block:: rst

   ======== ========
   heading1 heading2
   ======== ========
   row1x1   row2x1
   row1x2   row2x2
   row1x3   row2x3
   ======== ========

The template renders as:

======== ========
heading1 heading2
======== ========
row1x1   row2x1
row1x2   row2x2
row1x3   row2x3
======== ========

The use of '=' between the headings and the rows in simple tables tags the
content of the headings as the table header. Do not add emphasis to the
contents of the table header using \*\*.

Use grid tables for all other scenarios involving tables. For example:

+-----------------+------------------------+--------------+------------+
| Name            | Purpose                | Known        | References |
| (or brand name) |                        | Applications |            |
+=================+========================+==============+============+
| Super Glue      | Glues things together  | Small car    | Quick Fix, |
|                 | with extra strength.   | repairs.     |  2010.     |
+-----------------+------------------------+--------------+------------+
| Masking Tape    | Stops paint from       | Painting     | Master     |
|                 | covering a surface     | walls.       | Painter,   |
|                 | allowing for sharp     |              | 2007.      |
|                 | edges.                 |              |            |
+-----------------+------------------------+--------------+------------+

This template can help you create grid tables:

.. code-block:: rst

   +------------------------+------------+----------+----------+
   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
   | (header rows optional) |            |          |          |
   +========================+============+==========+==========+
   | body row 1, column 1   | column 2   | column 3 | column 4 |
   +------------------------+------------+----------+----------+
   | body row 2             | ...        | ...      |          |
   +------------------------+------------+----------+----------+

The use of '=' in grid tables is used to separate the table header from the
table body. Do not add emphasis to the contents of the table header using
\*\*.