How can I have Sphinx tables fit to width?

Question

Consider this table, where pyeval is a macro that evaluates an expression and replaces it with its value (so I can avoid hardcoding values in the documentation):

======================= ===========================================
Subsytem                Default path
======================= ===========================================
:pyeval:`constants.FOO` :pyeval:`pathutils.DEFAULT_FOO_STORAGE_DIR`
:pyeval:`constants.BAR` :pyeval:`pathutils.DEFAULT_BAR_STORAGE_DIR`
:pyeval:`constants.BAZ` :pyeval:`pathutils.DEFAULT_BAZ_STORAGE_DIR`
======================= ===========================================

This renders with this HTML:

<table border="1" class="docutils">
  <colgroup>
    <col width="40%">
    <col width="60%">
  </colgroup>
  <thead valign="bottom">
    <tr class="row-odd">
      <th class="head">Subsystem</th>
      <th class="head">Default storage path</th>
    </tr>
  </thead>
  <tbody valign="top">
    <tr class="row-even">
      <td><tt class="docutils literal"><span class="pre">foo</span></tt></td>
      <td><tt class="docutils literal"><span class="pre">/srv/badp/foo-path/</span></tt></td>
    </tr>
    <tr class="row-odd">
      <td><tt class="docutils literal"><span class="pre">bar</span></tt></td>
      <td><tt class="docutils literal"><span class="pre">/srv/badp/bar-path/</span></tt></td>
    </tr>
    <tr class="row-even"><td><tt class="docutils literal">
      <span class="pre">baz</span></tt></td>
      <td><tt class="docutils literal"><span class="pre">/var/run/badp/baz-path/</span></tt></td>
    </tr>
  </tbody>
</table>

Because of the macro, the amount of width I have to give to the Subsytem column is only slightly smaller than the column Default path gets, but the contents of its column are much shorter. Since Sphinx tries to be "helpful", it tries to transfer the ratio of widths in the source file to the HTML page (notice the colgroup tag) and the result is quite uneven:

Notice that Chrome (just like Firefox does) "helpfully" breaks at the hyphenation point and, since this is a path, I don't get to change hyphens to non breaking hyphens; people are just too likely to copy paste these values.

If I remove the colgroup element, however, I get the table I want.

How can I tell Sphinx to please be less smart with my table?

Answer 1

I too have run into this problem. Reading the docutils source, it appears that the colgroup widths are calculated using the number of dashes for the column in the separator lines for grid tables and the number of characters in the longest column entry for the column in simple tables as used here.

An attempt to write a custom directive to generate a table without a colgroup ran into what appears to be a bug in docutils in that later processing of the generated elements expects a colgroup to be present.

One technique I have used is to use aliases to create data items that are closer in length to their real text. For example:

.. |FOO| replace:: :pyeval:`constants.FOO`

which helps but isn't perfect.

An experiment disabling the colgroup element using the following css

colgroup { display: none; }

worked perfectly on FireFox but hid the enter table in IE9 so clearly this isn't an acceptable solution either.

Answer 2

What seems to work (at least in Firefox) is to reset the col widths:

table.docutils col {
    width: auto;
}