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 下载地址

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

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

texlive 检查是否安装成功

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

texstudio 安装

texstudio 下载地址

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

生成 PDF 文档

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

打开 sphinx 的 conf.py 文件, 添加以下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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 内容如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# .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: .

requirements.txt 内容如下

1
2
3
4
sphinx==5.0.2

sphinx-rtd-theme==1.0.0

详细 sphinx 工程请参考以下工程:

https://gitee.com/tutubinary/sphinx-readthedocs-temp.git

工程准备好后,在 readthedocs 上导入一个项目等项目构建成功后,即可在 下载 页面下载pdf手册

==如果自己工程有问题, 就仔细对比上述提到的三个文件内容==