See the "Table suggestions" thread on the docutils develop mailing list . A summary of the patches:
- The table directive (for simple and grid tables) now accepts a :widths: option, accepting a list of integers for manually specifying the column widths (analogous to csv and list tables).
- The :widths: option for all table directives (table, csv-table and list-table) will now also accept an 'auto' value to instruct the backend to automatically size the columns based on their contents.
- For all tables (so also simple/grid tables without table directive), :widths: is assumed to be 'auto' when the :widths: option is not specified, so that :widths: behavior is uniform across the table directives. I believe the choice for ":widths: auto" is obvious for csv and list tables. For simple/grid tables, this is debatable, but I'd go for consistency across the different table formats.
- The column widths (based on the ASCII grid, or equal widths for csv/list tables) are passed as a colspec attribute as before. A tgroup attribute 'colwidths' instructs the backend to automatically size the columns or use the supplied widths. This allows backends with limited means of automatically sizing the columns (such as LaTeX) to fall back to the supplied column widths.
- The (simple/grid) table directive additionally accepts a 'grid' value for :widths: to instruct the backend to use the column widths as determined from the ASCII column widths (this is the current behavior).
As discussed in the "Table suggestions" thread, I initially planned to remove the colwidth attributes from the colspec doctree nodes for :widths: auto, but this would be problematic for the LaTeX backend. I believe the patches provide a pragmatic solution to this.
All backend should continue to work as before, as in the doctree, the tgroup will only have the extra 'colwidths' attribute. I can adjust the HTML backend to automatically size columns if these patches are accepted. I suggest leaving the LaTeX backend as-is for now.