强制 Sphinx 使用 longtable 指令，在长表中正确添加分页符

Question

我正在开展一个项目，我们在该项目中生成 HTML 和 PDF 文档。

当表格超过 30 行时，sphinx 会正确使用 Latex longtable 包。但是，对于较小的表，它会使用 tabulary 包。

我的问题是我有一些表少于 30 行，但由于行很大，我需要分页。

根据我所有的阅读（具体来说，这里：https://github.com/sphinx-doc/sphinx/issues/1898），似乎我应该通过指定“：class：longtable”来强制 sphinx 使用 longtable

不幸的是，我没有成功添加此规范，因为我的表没有使用单独的指令指定。

我的表是这样定义的：

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | Detail                   |
+========+=================+==========================+
| 1      | Testing         | Testing  Testing Testing |
+--------+-----------------+--------------------------+

我得到的所有在线示例都使用列表表或 csv 表，然后将 longtable 命令添加为相关指令的一部分。例如：

.. tabularcolumns:: |p{1cm}|p{7cm}|

.. csv-table:: Lorem Ipsum
   :file: _files/lorem-tab.csv
   :header-rows: 1
   :class: longtable

我已经试过了，但不幸的是它没有用：

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|
   :class: longtable

+--------+-----------------+--------------------------+
| Step # | Process Step(s) | Detail                   |
+========+=================+==========================+
| 1      | Testing         | Testing  Testing Testing |
+--------+-----------------+--------------------------+

尝试制作 pdf 时出现以下异常：

! Package array Error:  Illegal pream-token (:): `c' used.

See the array package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.663 :class: longtable}

Answer 1

在与同事进行 Rubber-duck 调试之后，我们确定我需要添加 ..table 指令。这然后包装了我的简单 table 并为 :class: 定义提供了一个位置。

所以我的table现在定义如下：

.. tabularcolumns:: |p{1cm}|p{4cm}|p{10cm}|

.. table:: My Table
   :widths: auto
   :class: longtable

   +--------+-----------------+--------------------------+
   | Step # | Process Step(s) | Detail                   |
   +========+=================+==========================+
   | 1      | Testing         | Testing  Testing Testing |
   +--------+-----------------+--------------------------+

这对我们的问题进行了排序，它仍然从 tabularcolumns 指令中读取列规范。

强制 Sphinx 使用 longtable 指令，在长表中正确添加分页符

Force Sphinx to use longtable directive, to correctly add page breaks in long tables

latex

python-sphinx