我怎样才能让Sphinx表适合宽度？

Question

考虑这个表,其中pyeval是一个宏,它评估一个表达式并用它的值替换它(所以我可以避免文档中的硬编码值):

======================= ===========================================
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`
======================= ===========================================

这将使用此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>

由于宏,我必须给Subsytem列的宽度仅略小于列Default path,但其列的内容要短得多.由于Sphinx试图"有用",它会尝试将源文件中宽度的比例传递给HTML页面(注意colgroup标记),结果非常不均匀:

请注意,Chrome(就像Firefox一样)在连字点处"有用"地断开,因为这是一条路径,所以我不会将连字符更改为非连字符; 人们太可能复制粘贴这些值.

colgroup但是,如果我删除元素,我会得到我想要的表格.

我如何告诉Sphinx请不要对我的桌子不太聪明？

Answer 1

我也遇到过这个问题。阅读 docutils 源代码，似乎 colgroup 宽度是使用网格表分隔线中列的破折号数量以及简单表中列的最长列条目中的字符数来计算的，如此处所用。

尝试编写自定义指令来生成没有 colgroup 的表，但遇到了 docutils 中的错误，因为生成的元素的后续处理需要存在 colgroup。

我使用的一种技术是使用别名来创建长度更接近真实文本的数据项。例如：

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

这有帮助，但并不完美。

使用以下 css 禁用 colgroup 元素的实验

colgroup { display: none; }

在 FireFox 上工作得很好，但在 IE9 中隐藏了输入表，所以显然这也不是一个可接受的解决方案。