如何通过rst2pdf/Sphinx正确转换跨多页的表格行单元格？

• rst2pdf崩溃：其依赖的ReportLab渲染引擎旧版本默认不支持单个表格单元格跨页拆分，当单元格内容高度超过单页可用帧高度时，引擎反复尝试排版失败，触发More than 10 pages generated without content的保护机制直接退出。
• latexpdf排版错乱：默认LaTeX表格配置未开启长内容自动断行规则，无分隔符的连续字符（如长串代码、URL、哈希值）不会主动折行，最终溢出页边距显示异常。

两种构建方式都可以通过配置修复，且均能同时兼容空格分隔的常规文本、无分隔符连续文本的自动换行需求。

修复rst2pdf崩溃问题 #

1. 先升级rst2pdf到0.98及以上版本，该版本后已正式支持表格单元格跨页拆分能力：
   pip install --upgrade rst2pdf
2. 在项目的conf.py（Sphinx项目）或rst2pdf自定义配置文件中加入以下配置：

# 开启表格跨页拆分能力
pdf_table_split = True
# 开启全局断词支持
pdf_hyphenation = True
# 配置默认表格样式
pdf_default_table_style = [
    ('VALIGN', (0,0), (-1,-1), 'TOP'),
    # 开启CJK换行模式：有空格的文本按单词边界折行，无空格连续文本按字符宽度折行
    ('WORDWRAP', (0,0), (-1,-1), 'CJK'),
]

3. 如果单元格内包含预格式化内容（如代码块、无空格长串），可在对应内容前添加class指令指定折行规则：

.. class:: allow-wrap

| 此处填入超长单元格内容

配置完成后重新构建，超高单元格会自动在页边界拆分跨页显示，不会再触发崩溃。

修复latexpdf排版异常问题 #

修改Sphinx项目conf.py中的LaTeX配置，引入必要包支持长表格跨页、长文本自动折行：

latex_elements = {
    'preamble': r'''
% 引入跨页表格、自适应列宽、长文本折行依赖包
\usepackage{longtable}
\usepackage{tabularx}
\usepackage{seqsplit}
% 配置长表格边距
\LTleft=0pt
\LTright=0pt
% 定义自适应折行列类型：常规文本按词折行，无空格连续文本按字符宽度折行
\newcolumntype{Z}{>{\raggedright\seqsplit}X<{\unskip}}
% 调整表格行高避免内容拥挤
\renewcommand{\arraystretch}{1.2}
''',
}

如果文档中存在手动编写的LaTeX表格，将列格式替换为上面定义的Z类型即可自动适配折行规则；reStructuredText编写的表格会自动套用该配置，不需要额外修改表格内容。遇到超长URL、代码片段等特殊内容时，也可以手动用\seqsplit{内容}包裹获得更精准的折行效果。

配置完成后可分别用两类长文本测试：

• 空格分隔的常规文本：优先按单词边界折行，不会出现生硬截断单词的问题
• 无分隔符连续文本：按列宽自动在字符边界折行，不会溢出页边距
• 超高单元格：自动在分页位置拆分内容，跨多页连续显示，无崩溃、内容丢失问题

内容的提问来源于stack exchange，提问作者abumandour