在 reStructuredText 的 Sphinx 处理中保留 table 单元格换行符

Question

我有一个 reStructuredText table，其中一行如下：

+------+-----------------------------+
| Mask | The bit mask:               |
|      | [bit 0] Description of bit0 |
|      | [bit 1] And bit1            |
+------+-----------------------------+

Sphinx生成的cell（以HTML为例）是这样的：

<td><p>The bit mask:
[bit 0] Description of bit0
[bit 1] And bit1</p></td>

我想要制作的是这个（或类似的），其中至少在每个新行之前强制换行：

<td><p>The bit mask:
<br>[bit 0] Description of bit0
<br>[bit 1] And bit1</p></td>

有没有一种方法可以配置 Sphinx 以遵守 reStructuredText table 单元格中的行？

（供参考，这里是整个table当前生产的：）

<table class="docutils align-default">
   <colgroup>
      <col style="width: 17%" />
      <col style="width: 83%" />
   </colgroup>
   <tbody>
      <tr class="row-odd">
         <td>
            <p>Mask</p>
         </td>
         <td>
            <p>The bit mask:
               [bit 0] Description of bit0
               [bit 1] And bit1
            </p>
         </td>
      </tr>
   </tbody>
</table>

Answer 1

通常有两种简单的方法可以保证 reST 中的换行或对齐。

1. 使用Paragraphs，如下：

+------+-----------------------------+
| Mask | The bit mask:               |
|      |                             |
|      | [bit 0] Description of bit0 |
|      |                             |
|      | [bit 1] And bit1            |
|      |                             |
+------+-----------------------------+

将给予：

<table class="docutils align-default">
   <tbody>
      <tr class="row-odd">
         <td>
            <p>Mask</p>
         </td>
         <td>
            <p>The bit mask:</p>
            <p>[bit 0] Description of bit0</p>
            <p>[bit 1] And bit1</p>
         </td>
      </tr>
   </tbody>
</table>

2. 使用Line Blocks，如下：

+------+-------------------------------+
| Mask | | The bit mask:               |
|      | | [bit 0] Description of bit0 |
|      | | [bit 1] And bit1            |
+------+-------------------------------+

将给予：

</table>
   <tbody>
      <tr class="row-odd">
         <td>
            <p>Mask</p>
         </td>
         <td>
            <div class="line-block">
               <div class="line">The bit mask:</div>
               <div class="line">[bit 0] Description of bit0</div>
               <div class="line">[bit 1] And bit1</div>
            </div>
         </td>
      </tr>
   </tbody>
</table>

生成的 <div class="line"></div> 将像段落一样工作并保持对齐。这是由 reST 规范保证的，因此即使您的输出不是 HTML，也应该有适当的机制来保证结果是一致的。

在 reStructuredText 的 Sphinx 处理中保留 table 单元格换行符

Preserve table cell line breaks in Sphinx processing of reStructuredText

restructuredtext

html-table

line-breaks

python-sphinx