Sphinx 如何生成 PDF 文档 [2024.3.1]
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 下载地址
这个安装很简单, 没有特殊要求
生成 PDF 文档
texlive 和 texstudio 安装好后就可以使用 sphin 生成文档了
打开 sphinx 的 conf.py 文件, 添加以下代码:
1 | latex_elements = { |
- 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 | # .readthedocs.yaml |
requirements.txt 内容如下
1 | sphinx==5.0.2 |
详细 sphinx 工程请参考以下工程:
工程准备好后,在 readthedocs 上导入一个项目等项目构建成功后,即可在 下载 页面下载pdf手册
==如果自己工程有问题, 就仔细对比上述提到的三个文件内容==