docs/gettingstarted/writingdocs/styleguide/styleguide02table.rst

   1 .. _styleguide02table:
   2
   3 ******
   4 Tables
   5 ******
   6
   7 There are two types of tables with different syntax, `Grid Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_, and `Simple Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>`_.
   8
   9 Grid Tables
  10 ___________
  11
  12 `Grid Tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables>`_ are described with a visual grid made up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines (row separators). The equals sign ("=") may be used to separate optional header rows from the table body. The vertical bar ("|") is used for vertical lines (column separators). The plus sign ("+") is used for intersections of horizontal and vertical lines.
  13
  14 Here is example code for a grid table in a *.rst* file:
  15
  16 .. code-block:: console
  17
  18         +------------------------+------------+----------+----------+
  19         | Header row, column 1   | Header 2   | Header 3 | Header 4 |
  20         | (header rows optional) |            |          |          |
  21         +========================+============+==========+==========+
  22         | body row 1, column 1   | column 2   | column 3 | column 4 |
  23         +------------------------+------------+----------+----------+
  24         | body row 2             | Cells may span columns.          |
  25         +------------------------+------------+---------------------+
  26         | body row 3             | Cells may  | - Table cells       |
  27         +------------------------+ span rows. | - contain           |
  28         | body row 4             |            | - body elements.    |
  29         +------------------------+------------+---------------------+
  30
  31 This example code generates a grid table that looks like this:
  32
  33 +------------------------+------------+----------+----------+
  34 | Header row, column 1   | Header 2   | Header 3 | Header 4 |
  35 | (header rows optional) |            |          |          |
  36 +========================+============+==========+==========+
  37 | body row 1, column 1   | column 2   | column 3 | column 4 |
  38 +------------------------+------------+----------+----------+
  39 | body row 2             | Cells may span columns.          |
  40 +------------------------+------------+---------------------+
  41 | body row 3             | Cells may  | - Table cells       |
  42 +------------------------+ span rows. | - contain           |
  43 | body row 4             |            | - body elements.    |
  44 +------------------------+------------+---------------------+
  45
  46
  47 Simple Tables
  48 _____________
  49
  50 `Simple tables <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>`_ are described with horizontal borders made up of "=" and "-" characters. The equals sign ("=") is used for top and bottom table borders, and to separate optional header rows from the table body. The hyphen ("-") is used to indicate column spans in a single row by underlining the joined columns, and may optionally be used to explicitly and/or visually separate rows.
  51
  52 Simple tables are "simpler" to create than grid tables, but are more limited.
  53
  54 Here is example code for a simple table in a *.rst* file.
  55
  56 .. code-block:: console
  57
  58         =====  =====  =======
  59           A      B    A and B
  60         =====  =====  =======
  61         False  False  False
  62         True   False  False
  63         False  True   False
  64         True   True   True
  65         =====  =====  =======
  66
  67 This example code generates a simple table that looks like this:
  68
  69 =====  =====  =======
  70   A      B    A and B
  71 =====  =====  =======
  72 False  False  False
  73 True   False  False
  74 False  True   False
  75 True   True   True
  76 =====  =====  =======