Sphinx+reStructuredText：调整PDF样式

本文为快问快答形式，分享使用 Sphinx+reStructuredText 发布PDF过程中，调整PDF样式的方法和经验。另外，实现方法可能有多种，本文仅分享笔者工作中的经验，不代表是唯一的或者最优的做法。

Q6： 如何修改PDF中标题级的颜色？

在 conf.py 文件中找到 latex_elements中使用 sphinxsetup 调整。
除标题颜色外，也可以修改其他标语的颜色。以下仅为示例：

sphinxsetup.png

Q7： 为什么在发布的PDF中有些图片会错位（和文本不在同一页面）？

Latex 中图片和表格的排版使用浮动体（float）设置在页面的位置，默认设置为 htbp (here此处, top页顶, bottom页底, page独立一页)。因此，在当前页面无法放下图片时，图片可能会悬浮到下一页面，可能造成图片和文本的“错位”。
为了让图片严格出现在对应的文本处，可以做如下修改：

1. 在 conf.py 文件中找到 latex_elements，并添加以下命令行：

'figure_align': 'H',

figure_align 设置.png

Q8： 跨页表格，如何让表头在每页开头重复显示？

对于行数较多的大型表格，如需每页开始都重复显示标题行，可以为表格添加 class: longtable 的属性即可。
以CSV表格为例，写法如下：

.. csv-table:: Table Title
   :class: longtable

Q9：如何让图片和表格自动编号？

1. 在 conf.py 文件中设置 numfig = True：
   image.png
2. RST文件中，使用 numref 引用图片和表格。 “%” 为占位符，代表自动编号。

:numref:`Fig. %s <figure-label>`

另外，

1. 可以在 conf.py 文件修改 numfig_format 设置图片和表格的自动编号的标签文本。默认：
   • Fig. %s 为 figure的自动编号
   • Table %s 为 table的自动编号
   • Listing %s 为code-block的自动编号
   • Section %s 为 section的自动编号
2. 可以在 conf.py 文件修改 numfig_secnum_depth 设置起始编号。默认起始编号为 “1”。

详细信息，可以参考 Sphinx configuration 官方文档