Sphinx+reStructuredText：调整PDF样式

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

使用 Sphinx+reStructuredText 生成PDF时，默认经过的是 reStructuredText 文件 > tex 文件 > PDF 文件的过程，即使用的是 latex engine进行PDF的输出。因此，在自定义输出的PDF样式时，很多的调整都是基于 latex 语法。在此，推荐一本latex的入门书籍，刘海洋的《Latex入门》。有需要的小伙伴可以联系我，我可以分享本书的电子档。

刘海洋《Latex入门》.png

Q1: 如何修改文档页面尺寸为 A4？

使用 Sphinx+reStructuredText 生成PDF时，默认的页面大小是 Letter 尺寸（Letter是美国比较普遍使用的一个纸张尺寸，具体的尺寸为 8.5英寸 * 11英寸）。而国内则普遍使用A4纸张尺寸，具体尺寸为 210mm297mm，折合英制为 8.268英寸11.69英寸。因此，会出现需要调整文档页面尺寸为A4的现象。

如何调整：

1. 在默认的 Sphinx 环境（默认是 source 文件夹）中找到 conf.py 文件。
2. 在 latex_elements 中添加 papersize: a4paper 行。如下示例：

image.png

3. 此外，还可以进一步设置页面版心的尺寸，即页面内容显示区域离上下左右边距的大小。
   以上下左右边距设置为 2cm 为例，在 latex_elements 添加以下命令：

latex_elements{
   'geometry': r' \usepackage[left=2cm,right=2cm,top=2cm,bottom=2cm]{geometry}',

}

Q2: 如何调整PDF字体？

默认情况下，Sphinx使用 latex engine 输出PDF，默认使用 Times，Helvetica，和 Courier 字体组合。因此，如果需要调整字体，可以使用 latex 中 font 包的用法，引入心仪的目标字体。

需要注意的是，font 宏包的使用仅适用于latex 发布引擎为 xelatex 和 lualatex 的情况。而Sphinx默认的latex engine为 pdflatex.

如需自定义发布出来的PDF的字体，可以参考下面的操作：

1. 使用 fc-list 命令，或者到 系统 font 目录下查看已有字体，确保系统中含有目标字体。

2. 在默认的 Sphinx 环境（默认是 source 文件夹）中找到 conf.py 文件。

3. 使用 xelatex latex 发布引擎。
   

   使用 xelatex 发布引擎.png

4. 在 latex_elements 使用 fontpkg 行。如下示例：

引入 fontpkg 包.png

Q3: 如何自定义页眉页脚

使用latex fancyhdr 宏包进行设置。

1. 在 conf.py 文件中，找到 latex_elements。
2. 根据需求设置页眉页脚。

fancyhdr 宏包的详细命令和参数，可参考刘海洋《Latex入门》一书中 P145-149。

Q4: 调整目录样式

使用 latex tocloft 宏包进行设置。

1. 在 conf.py 文件中，找到 latex_elements。
2. 以调整目录中制表位宽度为例，命令行示例如下：

latex_elements:{
   'premable': r'''
   usepackage{tocloft}
  \renewcommand\cftfignumwidth{4em} 
  \renewcommand\cfttabnumwidth{4em} 
  \renewcommand\cftsecnumwidth{4em} 
  \renewcommand\cftsubsecnumwidth{6em} 
  \renewcommand\cftparanumwidth{6em} 
'''
}

Latex tocloft 宏包中，对应的命令和参数如下：

tocloft 宏包命令和参数.png

详细设置，可参考刘海洋《Latex入门》一书的 P162-165。

Q5: 如何让每节（section）从新的页面开始？

1. 在 conf.py 文件中，找到 latex_elements。
2. 增加以下命令行：

latex_elements:{
   'premable': r'''
   newcommand{\sectionbreak}{\clearpage}
'''
}

如何修改全文文本对齐方式为左对齐？

默认输出的PDF中，正文文本对齐方式默认设置为“两端对齐”，但在英文文档中，有时候不太友好。所以，一般需要将文本对齐修改为“左对齐”。

1. 在 conf.py 文件中，找到 latex_elements。
2. 增加以下命令行：

latex_elements:{
   'premable': r'''
   \usepackage[document]{ragged2e}
'''
}

---

未完待续...