可以将多个段落替换为 reStructuredText 表格单元格吗? [英] Can multiple paragraphs be substituted into reStructuredText table cells?

问题描述

我有一个 reST 格式的表格，其中一些单元格包含长文本块(即多个段落或项目符号列表)并且它们会定期更新，例如:

I have a reST formatted table where some cells contain long blocks of text (i.e. multiple paragraphs or bulleted lists) and they get updated periodically, for example:

+-------+-----------------------+
|Cat    | Chunk that is updated |
|       | periodically.         |
|       |                       |
|       | Line #2, #3, etc      |
+-------+-----------------------+
|Dog    | Substitution means    |
|       | table boilplat static |
|       |                       |
|       | Line #2, #3, etc      |
+-------+-----------------------+

为了避免每次更新都维护表格样板，我首先尝试了 替换，但这仅适用于内联指令(如图像)和单行文本...不是多个段落:

To avoid maintenance of the table boilerplate every update, I first tried substitution, but that only works for inline directives (like image) and single-line-text... not multiple paragraphs:

.. |cellb1| replace:: Chunk that is updated periodically via copy-and-paste

.. |cellb3| replace:: Substitution means table boilerplate can remain static 

+-------+-----------------------+
|Cat    | |cellb1|              |
+-------+-----------------------+
|Dog    | |cellb3|              |
+-------+-----------------------+

第二种方法是 .. include:: 指令.这适用于多个段落，但代价是复杂性(内容现在在多个外部文本文件中错位).

A second approach is the .. include:: directive. That works fine for multiple paragraphs, but at the cost of complexity (content is now dislocated across multiple external text files).

+-------+-----------------------+
|Cat    | .. include:: xr1.txt  |
+-------+-----------------------+
|Dog    | .. include:: xr3.txt  |
+-------+-----------------------+

list-table 没有帮助，csv-table(因为内容包括逗号和引号字符).

list-table doesn't help, nor does csv-table (because content includes comma and quote chars).

.. csv-table:: Test csv-table with multi-paragraph
   :header: "a", "b", "c"

    Cat,"Chunk that is updated periodically via copy-and-paste.

    Line #2, #3, etc", "Kitten"
    Dog,"Substitution means table boilerplate can remain static.

    Line #2, #3, etc", "Puppy"

注意:csv-table 出现了一个附带问题，缩进和列数会影响 Sphinx 解析器，因此内容被格式化为块引用或定义列表.[编辑:请参阅下面的答案 - 由于 :header: 行的缩进不一致]

NB: A side-issue crops up with csv-table, indentation and number of columns affect the Sphinx parser, so content gets formatted as blockquote or definition list. [EDIT: see answer below - due to inconsistent indentation of the :header: line]

有没有更好的方法?

推荐答案

以下示例适用于我.请注意，空格非常棘手.在缩进任何内容时，我总是使用 4 个空格，包括诸如 :header: 之类的选项，因为它可以更轻松地检测问题并确保 Sphinx 正确解释空格.在您的示例中，您需要做的就是在 :header: 之前再添加一个空格，总共 4 个空格以使所有内容对齐.我还添加了一个枚举列表的示例.

The following example works for me. Note that whitespace is super tricky. I always use 4 spaces when indenting anything, including options such as :header:, because it makes it easier to detect issues and it ensures that whitespace is interpreted correctly by Sphinx. In your example, all you needed to do was add one more space before :header: for a total of 4 spaces to get everything aligned. I've also added an example of an enumerated list.

.. csv-table:: Test csv-table with multi-paragraph
    :header: "a", "b", "c"

    Cat,"Chunk that is updated periodically via copy-and-paste.

    Line #2, #3, etc", "Kitten"
    Dog,"Substitution means table boilerplate can remain static.

    Line #2, #3, etc", "Puppy"
    Walrus,"#.  List Item 1
    #.  List Item 2
    #.  List Item 3", "Pup"

这篇关于可以将多个段落替换为 reStructuredText 表格单元格吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！