Can multiple paragraphs be substituted into reStru

2019-08-18 12:12发布

问题:

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|              |
+-------+-----------------------+

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 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"

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]

Is there a better way?

回答1:

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"