Tables

Most tables in the documentation will take one of two forms:

  • constructed with the .. table:: directive, in which case the tables are ascii art. This form is not preferred, however, it is the only form that allows for rowspanning or columnspanning, so there are cases where only this form may be used.
  • constructed with the .. csv-table:: directive, in which case the table is a csv list. This form is preferred, and is seen more predominantly in the documentation.

Table Cookbook

The following discussion focuses solely on .. csv-table::-type tables. Much of the formatting applicable to these, as applied via the :class: attribute of the table, will apply equally to .. table::-style tables as well.

Plain table. The simplest csv-style table might appear as follows.

.. csv-table::

   This, is, my table
   It, has, default formatting
This is my table
It has default formatting

Style-wise, a table will have, by default: a top border, a bottom border, no row stylings (shading or underlines, etc.), no vertical borders. Titles and headers, however, are available, per next. Also, text-alignment in table columns is left by default. Columns will be of equal size.

Plain table with title and header row. A title is added by putting something following the double colon on the directive; header row is added with the :header: option; as with table content, the header labels are comma-delimited.

.. csv-table:: Simple Table
   :header: Noun, Verb, Direct Object

   This, is, my table
   It, has, default formatting
Table 2: Simple Table
Noun Verb Direct Object
This is my table
It has default formatting

Default style observations: text in the first cell of the header row is left-aligned, the following cells are centered. The header has a shaded background and bold text. The table title is centered, italicized, and auto-numbered. Note the numbering is based on an absolute count of the tables in the document. Even though the first table did not feature a title (and therefore no number either), it was still “Table 1”, making the table that follows it “Table 2” as seen.

Escaping commas, column widths. The easiest way to include a comma in the cell contents is to wrap the cell contents in quotes. This can be done on a per-cell basis. Column widths are set with the :widths: option. This option takes integers only (errors if you provide a float or something like “43%”), must match the number of columns in the table (errors, again), and operates as a ratio (column width = supplied value/total of all supplied values).

.. csv-table:: Table with Sized Columns
   :header: Noun, Verb, Direct Object
   :widths: 1, 1, 4

   This, is, "an elongated, wordier table"
   It, "continues,", "however, to use default formatting"
Table 3: Table with Sized Columns
Noun Verb Direct Object
This is an elongated, wordier table
It continues, however, to use default formatting

Alternative to comma escaping: there is also an option :delim: for csv-tables that can be used to redefine the delimiter to something other than a comma; refer to docutils docs if interested.

Note up to this point, all table behavior is default: nothing more than standard reST markup has been used to build the preceding examples. From here, the presentation will focus on the use of the :class: option to access table adjustments/stylings as built into the style sheet.

Column Text-Alignment. If a column needs to be center or right aligned, use :class: to specify as shown.

.. csv-table:: Table with Sized Columns
   :header: Noun, Verb, Direct Object
   :widths: 1, 1, 4
   :class: col1center col2center col3right

   This, is, "an elongated, wordier table"
   It, "continues,", "however, to use default formatting"
Table 4: Table with Sized Columns
Noun Verb Direct Object
This is an elongated, wordier table
It continues, however, to use default formatting

The styles observe the naming convention: prefix = “col”, column number = “#”, alignment style = “center” or “right”. The value of # may be as high as 8. Remember, table text-alignment is left by default, so there are no corresponding “col1left” “col2left” etc. styles. Note that, on the rendered table, the column headings do not match the styles applied: column one in the heading row is always left aligned, and all following column heading labels are centered. It will usually be better visually to not center or right align the first column text.

Shading, Underlines. Shading (“stripes”) and underlining rows (“underrow”) each have their own :class: designation.

.. csv-table:: Table with Shaded Rows and Row Underlining
   :header: Noun, Verb, Direct Object
   :widths: 1, 1, 4
   :class: col2center col3right underrow stripes

   This, is, "an elongated, wordier table"
   It, "continues,", "however, to use default formatting"
Table 5: Table with Shaded Rows and Row Underlining
Noun Verb Direct Object
This is an elongated, wordier table
It continues, however, to use default formatting

These styles will not work well with attempts to “stack” cell contents (put three lines of text in one cell, for instance).

Mix and Match. All above options should work independently of one another; varying the options in use allows a wide variety of possibilities. Also, some of the options can be used to achieve effects, within limits.

.. csv-table::
   :header: Property, Value, Unit
   :widths: 4, 1, 1
   :class: col2right, underrow

   shear modulus (`G`), 2.80, GPa
   bulk modulus (`K`),  3.90, GPa
   density (`ρ`), 2600.00, kg/m\ :sup:`3`
   cohesion (`c`), 3.45, MPa
   friction angle (`α`), 30.00, °
   dilation angle (`ψ`), 30.00, °
Property Value  
shear modulus (\(G\)) 2.80 GPa
bulk modulus (\(K\)) 3.90 GPa
density (\(ρ\)) 2600.00 kg/m3
cohesion (\(c\)) 3.45 MPa
friction angle (\(α\)) 30.00 °
dilation angle (\(ψ\)) 30.00 °

For the above, having numbers with exactly the same number of digits after the decimal gives the appearance of decimal alignment in the second column when paired with right text alignment for the column.

Blank. Use :class: blank for the common case where a “non-table” is being used solely to achieve vertical alignment. Options and other classes may still be needed. “Blank” turns off the default top and bottom border.

.. csv-table::
   :class: blank col2right col3right
   :widths: 2, 1, 1, 12

   where:, `n`       , = , is the number of faces on the block;
         , `i`
         , `A_0`     , = , required force to stabilize the wedge;
         , `W`       , = , weight of the wedge;
         ,"`σ_{n,i}`", = , normal stress acting on the th face of the wedge;
         , `A_i`     , = , the area of the face of the wedge;
         , `ρ_i`     , = , the friction angle on the face of the wedge;
         , `α_i`     , = , the complement of the joint dip angle that creates the face;
         , `k_{si}`  , = , shear stiffness of the joint;
         , `k_{ni}`  , = , "normal stiffness of the joint; and,"
         , `i_i`     , = , roughness angle of the joint.
where: \(n\) = is the number of faces on the block;
  \(i\)    
  \(A_0\) = required force to stabilize the wedge;
  \(W\) = weight of the wedge;
  \(σ_{n,i}\) = normal stress acting on the th face of the wedge;
  \(A_i\) = the area of the face of the wedge;
  \(ρ_i\) = the friction angle on the face of the wedge;
  \(α_i\) = the complement of the joint dip angle that creates the face;
  \(k_{si}\) = shear stiffness of the joint;
  \(k_{ni}\) = normal stiffness of the joint; and,
  \(i_i\) = roughness angle of the joint.

Always remember to enclose a cell entry that contains a comma (even one that appears in math, as above) in quotes!

Some things worth noting above: 1) table cells may be blank (rows 2-11 do not have an entry in the first column), and 2) an insufficient number of cell entries/commas is acceptable (look at the markup of the second row); “missing” columns are constructed automatically. However, if the number of header entries & width entries do not match, or if either of these are exceeded by any given row’s entries (i.e., # of commas in a row \(≥\) number of widths/header labels), an error results and no table is rendered in output. 3) Because sphinx ignores white space, if it helps you can vertically align your table column data as seen.