Tables

Note

If rowspanning or columnspanning[1] is required, then the base .. table:: directive is needed. See Docutils: Tables Reference for information on construction of these. See the first table in Highway Loading of an Arch Bridge for a simple example in ICG docs.

In general, prefer to use .. csv-table::, which presents table content as a comma separated value (csv) list. This is the table type used predominantly throughout ICG docs.

At this time, there is no “standard” for tables in ICG documentation. If there are questions about how a table should appear, please ask for help. If help is presently unavailable, then the next best thing will be to copy an existing table in the docs that seems to match the current need.

Table Cookbook

The following examples all use .. csv-table::-type tables, though the :class: options shown below would work on .. table:: as well.

Formatting with Options

Plain table

The simplest csv-style table might appear as follows.

This

is

my table

It

has

default formatting

 
.. csv-table::

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

With no options provided at all, this table illustrates the default presentation of a table: a top border, a bottom border, no row stylings (shading or underlines, etc.), no vertical borders, left text-alignment in table cell, with of table auto-determined, columns widths will be autodetermined (and equal to the narrowest possible presentation).

Plain table with title and header row added

A title is added by putting a title string the double colon on the directive. The header row is added with the :header: option.

Table 2: Simple Table

Noun

Verb

Direct Object

This

is

my table

It

has

default formatting

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

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

Text in the first cell of the header row is left-aligned, the following cells are centered. All header row content has a shaded background and bold text. The table title is centered, italicized, and auto-numbered. Table 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

If cell content must include a comma, 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, must match the number of columns in the table, and operates as a ratio (column width = supplied value/sum of all supplied values).

Table 3: Table with Sized Columns

Noun

Verb

Direct Object

This

is

an elongated, wordier table

It

continues,

however, to use default formatting

 
.. 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"

Formatting with Classes

Further formatting options are available with style classes defined by ICG, illustrated next.

Column Text-Alignment

To center- or right-align a column, use the :class: option colXcenter or colXright (where X is the column number to text align, valid values range 1-8). There are no colXleft classes, as cell content is left-aligned by default.

Table 4: Table with Sized Columns

Noun

Verb

Direct Object

This

is

an elongated, wordier table

It

continues,

however, to use default formatting

 
.. 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"

Note, as seen, above, the text-alignment classes are not applied to the table header.

Shading, Underlines

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

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

 
.. 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"
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.

Property

Value

Unit

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

°

 
.. csv-table::
   :header: Property, Value,
   :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, °

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.

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.

 
.. 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.

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.

Resources for Working with Tables

Docutils: csv-table directive
Docutils: Tables Reference
Useful Grid (ASCII) Table Utility[2]

Endnote