4.9. Sphinx 生成 PDF¶
4.9.1. 个人心得¶
有必要在这里先写上个人心得：环境搭建太麻烦，结果输出不够理想！
latex 环境安装
在 Windows 下需要安装 latex 环境
安装 Miktex 软件，软件文件名为 basic-miktex-21.12-x64.exe
Miktex 需要 perl 环境，所以还要安装 perl 环境。
perl 环境安装 strawberryperl
软件名：strawberry-perl-5.32.1.1-64bit.msi
验证安装成功：在命令行界面输入 perl –version
命令行生成
切换到项目主目录下，运行
make latex 将命令行目录切换到 build/latex/ 下，再运行
make 首次运行需要安装很多插件，将显示弹出窗口的勾去掉，就会自动安装到完。下次运行相对就快了。
Note
生成的文件在当前目录下，总体来说挺不错，生成的目录我个人相当喜欢。 不过字体太小了，目前不知道怎么调，不够理想！ 个人还是不太喜欢通过这种方式生成的 pdf，总体来说不太理想！ 并且环境搭建过程实在是太麻烦了！
Sphinx make 命令
我们可以通过 make 来看 sphinx 到底支持了多少选项。
$make
Sphinx v4.3.2
Please use `make target' where target is one of
html to make standalone HTML files
dirhtml to make HTML files named index.html in directories
singlehtml to make a single large HTML file
个人注解：
make html: 最常用选项，生成标准的 html 文件
make singlehtml: 和 make html 相比，生成了单独一个大的 html 文件。并且少了最前面的一页导航栏。个人觉得导航栏还是很重要的。
make clean: 今天(2022-01-06)才知道有这个选项，删除掉生成文件夹里的内容。平时在添加一个新的文档进去的时候，就需要删除掉 make html 生成的文件重新生成。才能拥有正常的侧边栏。但感觉这个命令挺危险的，如果有制作 htmlhelp 文件的话，一般都是需要处理过 htmlhelp 文件，这样一来，就可能连同这个也被删除掉了。感觉这个命令少用为妙，要删除手动删除比较妥当！
4.9.2. Sphinx 语法高亮支持的关键字¶
Code blocks with syntax highlighting
4.9.3. Sphinx 部署¶
简要说明一下如何将已经写好的 Sphinx 文档部署到互联网上，主要是通过 Read the Docs 这个网站部署的。 该网站免费托管一些开源文档，所以在 github 里面的 private 项目的文档在这里是无法托管的。
1.到该网站(Read the Docs)下注册一个账号；
2.在 github 新建一个项目，以下用 <address> 来表示在此处获得的 https 地址；
3.在本地用 sphinx-quickstart 新建 sphinx 项目，然后和正常一样在里面写文档。
4.在该项目的根路径(运行 make html)下初始化 git，并添加 .gitignore
git init
touch .gitignore
在 .gitignore 里面忽略掉 build 文件夹，因为该文件夹是生成 html 的文件夹，上传到 github 这个文件夹是不需要上传的。我们后续配置好 webhook 以后每一个 push 到远端的 commit 都会自动同步更新到 Read the Docs，不需要我们手动更新。
# .gitignore
build/
5.添加远程仓库路径并将已经写好的文档推送；
注：这里略过了 add 和 commit 的步骤
git remote add origin <address>
git push origin master
6.在 Read the Docs 自己的账号下导入项目
Import a project >> 手动导入
然后可以看到需要填一个表单： 名称：随便填，但是貌似不能填中文； 地址：上面生成的 <address> 填好好点击 下一页 之类的一直点下去就行。成功的话最后可以看到一个地址，类似于下面这个：
https://readthedocs.org/api/v2/webhook/XXXXX/
7.添加 webhook
以下这段英文配置方式来自： [2]
GitHub
Go to the Settings page for your project
Click Webhooks > Add webhook
For Payload URL, use the URL of the integration on Read the Docs, found on the project’s Admin > Integrations page. You may need to prepend https:// to the URL.
For Content type, both application/json and application/x-www-form-urlencoded work
Leave the Secrets field blank
Select Let me select individual events, and mark Branch or tag creation, Branch or tag deletion and Pushes events
Ensure Active is enabled; it is by default
Finish by clicking Add webhook. You may be prompted to enter your GitHub password to confirm your action.
Payload URL 就是第 6 步所得的地址。
[2] add webhook
这些配置完成后，我们平时只要 push 到 github 仓库就会自动同步到 Read the Docs 更新，相当方便。