`cloud_sptheme.ext.table_styling` - adds directives for styling tables¶

Changed in version 1.9: Added :header-alignment: directive.

Overview¶

This Sphinx extension replaces the default .. table:: directive with a custom one, that supports a number of extra options for controlling table layout on a per-column basis.

For example, the following snippet specifies relative widths for the three columns, changes the text alignment for each column, disables text-wrapping for the third column, and inserts dividers between the columns:

.. table:: Optional Caption
    :widths: 3 2 1
    :column-alignment: left center right
    :column-wrapping: true true false
    :column-dividers: none single double single

    =========== =========== ===========
    Width 50%   Width 33%   Width 16%
    =========== =========== ===========
    Line 1      This text   This text
                should wrap will always
                onto        be one line.
                multiple
                lines.
    Line 2      Centered.   Right-Aligned.
    Line 3      Centered    Right-Aligned
                Again.      Again.
    =========== =========== ===========

This will then result in the following table:

Optional Caption¶
Width 50%	Width 33%	Width 16%
Line 1	This text should wrap onto multiple lines.	This text will always be one line.
Line 2	Centered.	Right-Aligned.
Line 3	Centered Again.	Right-Aligned Again.

Directive Options¶

The enhanced .. table:: directive supports the following options:

:widths:

Sets proportional column widths

This should be a space-separated list of positive integers, one for every column. The columns widths will be allocated proportionally (e.g. 1 2 3 for a 3-column table means the columns will use 16%, 33%, and 50% of the total width, respectively).

:column-alignment:

Sets per-column text alignment

This should be a comma/space-separated list of the following strings: left, right, center, justify. These are interpreted one per column. Extra values are ignored; if not enough values are provided, the remaining columns will default to left.

Alternately this can be a single word containing just the first letters: e.g. lrcj would be interpreted the same as left right center justify.

:header-alignment:

Sets per-column text alignment for header rows.

This has the same format as :column-alignment:. If specified, all headers rows will use these alignment values instead of the default column alignments.

:column-wrapping:

Sets per-column text wrapping

This should be a comma/space-separated list of either yes/true or no/false. If yes (the default), words will wrap around if there is not enough horizontal space. If no, whitespace-wrapping will be disabled for that column. Extra values are ignored; if not enough values are provided, the remaining columns will default to true.

Alternately this can be a single word containing just the first letters: e.g. ttf is the same as true true false.

:column-dividers:

Add dividers between columns

This lets you specify custom vertical dividers between columns (ala what .. tabularcolumns:: allows under latex).

This should be a comma/space-separated list of none, single, or double; based on the type of divider you want. There should be one of these for the left side of the table, for between each column, and for the right side of the table (e.g. a 4 entries for a 3-column table). Extra values are ignored; if not enough values are provided, the remaining columns will default to none.

Alternately this can be a single word containing just the number: e.g. 0121 is the same as none single double single.

:column-classes:

Add per-column css classes.

This lets you specify css classes that will be assigned to each column, much like .. rst-class::. This should either be a space-separated list containing one class per column, or a comma-separated list containing multiple classes for each column, separated by spaces. Extra values are ignored; if there are not enough values, or there are blank entries, those columns will not be assigned any custom classes.

For example, a b, c , , d would assign the classes a b to column 1, c to column 2, no custom classes for column 3, and d to column 4.

:header-columns:

Specify number of “stub” columns

Should be a non-negative integer specifying the number of columns (starting with the left side) that should be treated as “stub” or “header” columns, and should be styled accordingly.

Configuration¶

This extension reads the following conf.py options:

table_styling_embed_css

Controls whether or not the custom css file should be included. Set to True to enable, False to disable. By default (None), enabled for all Sphinx themes which aren’t part of this package.

table_styling_class

By default, all HTML tables styled by this extension will have the css class "styled-table" added, to help with themeing support. Use this option to override with your own theme’s preferred css class.

Internals¶

Note

This extension gets the job done by adding custom css classes to every cell in the generated html table. It then inserts a custom css file which provides styling implementing relevant parts of the above directives. While this extension is primarily tested with cloud_sptheme, it should work with most Sphinx themes, any conflicts that occur are probably bugs.

Todo

make this autogenerate a matching .. tabularcolumns directive for latex.

Todo

allow :widths: to support em, in, %

cloud_sptheme.ext.table_styling - adds directives for styling tables¶