Sphinx 如何生成 PDF 文档 [2024.3.1]

前言

sphinx + rst 编写文档有以下优势：

简单易学
格式多样化: html/pdf
便于维护 (git)
跨平台

rst 标记语言可以很容易的输出 html 页面，但是想要输出 pdf 文档 会麻烦一点，这里就教大家如何生成 pdf 格式的文档。

rst 转 PDF 原理: 首先将 rst 转换为 tex, 再由 tex 转换为 PDF

下面会教两种方法给大家:

通过 texlive 和 TeXstudio 生成 pdf 文档
通道 readthedocs 代理服务器自动发生成 pdf 文档

第一种方法最靠谱， TeXstudio 软件在生成 pdf 文档时可以提示错误原因，方便找问题

第二种方法最简单，不需要再电脑上搭建环境，一旦出现错误很难查找问题所在

通过 texlive 和 TeXstudio 生成 pdf 文档

texlive 提供 tex 文档编写的各种依赖环境，安装包比较大，安装时间久
TeXstudio 提供 tex 文档编辑器，编辑、编译 tex 文档特别方便

这种方式最稳定， texlive 和 TeXstudio 安装比较麻烦

texlive 安装

texlive 安装特别慢，环境没设置好特别容易失败，在安装之前先把下面我遇到的问题提前说明，方便快速安装成功

关闭电脑的防火墙
打开 windwos 用户路径 %homepath%\AppData\Local 修改 temp 文件夹的权限，具体修改如下:
- “temp”右键–>“属性”—>“安全”—>单击选择“Users”—>“编辑”—>选择“读取和执行”、“列出文件夹内容”、“读取”—>“确认”。
- “temp”右键–>“属性”—>“常规”—>“高级”—>选择“可以存档文件夹”“除了文件属性外……”—>“确认”
- “temp”右键–>“属性”—>“常规”—>点击“只读”（使前面的框里什么都没有）
以管理员权限执行安装程序

texlive 下载地址

清华镜像 https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/
科大镜像 https://mirrors.ustc.edu.cn/CTAN/systems/texlive/Images/
南大镜像 https://mirrors.nju.edu.cn/CTAN/systems/texlive/Images/
香港镜像 https://mirror-hk.koddos.net/CTAN/systems/texlive/Images/

以管理员权限执行安装程序
以管理员权限执行安装程序
以管理员权限执行安装程序

点击 install-tl-windows.bat 文件进行安装即可，安装过程需要很久！！！

texlive 检查是否安装成功

添加环境变量, 把安装目录(2023\bin\windows) 添加到系统 path 环境变量下
执行 tex –version
执行 latex –version
执行 xelatex –version

texstudio 安装

texstudio 下载地址

https://www.texstudio.org/

这个安装很简单，没有特殊要求

生成 PDF 文档

texlive 和 texstudio 安装好后就可以使用 sphin 生成文档了

打开 sphinx 的 conf.py 文件，添加以下代码：

latex_elements = {
# Additional stuff for the LaTeX preamble.
# 'preamble': '''
# \\hypersetup{unicode=true}
# \\usepackage{CJKutf8}
# \\AtBeginDocument{\\begin{CJK}{UTF8}{gbsn}}
# \\AtEndDocument{\\end{CJK}}
# ''',
}
 
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'atk_hmi_manual.tex', '正点原子HMI用户手册',
     '作者: 正点原子团队', 'manual'),
]

latex_elements 网上都说要填，用于设置中文的字体，按照要求设置后 texstudio 一直提示错误，我这里留空了
latex_documents 根据需求设置即可

注意： latex 好像不支持 svg 矢量图片，所以不要在文档中嵌入，否则编译会报错

1	make latexpdf

就会在目录下生成 PDF文档: _build\latex

通过 readthedocs 服务器生成 PDF 文档

==该方式会随服务器的更新而失效，并不一定靠谱，当前记录时间 2024.3.1==

readthedocs 服务器对托管的文档有一定的格式要求，如下：

提供 .readthedocs.yaml
提供 requirements.txt
提供 pyproject.toml (空文件，不然服务器会出错)

.readthedocs.yaml 内容如下

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

formats:
  - pdf
  - htmlzip

# Set the version of Python and other tools you might need
build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
     # You can also specify other tool versions:
     # nodejs: "16"
     # rust: "1.55"
     # golang: "1.17"

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py
   fail_on_warning: true

# If using Sphinx, optionally build your docs in additional formats such as PDF
# formats:
#    - pdf

# Optionally declare the Python requirements required to build your docs
python:
   install:
   - requirements: docs/requirements.txt
   - method: pip
     path: .