使用Sphinx撰写电子文档

在日常工作中，写电子文档是个很普遍的事情。之前一直用Microsoft Word、Libreoffice Writer来写，但总感觉不方便，很多的精力都浪费在了调整格式上。而使用 Sphinx 来写电子文档，则可以把你从调整格式的泥潭中解放出来。Sphinx 是一款基于 Python的文档处理工具，Python官方的文档就是使用它来写的。Sphinx 使用reStructuredText 格式来定义文档，它比 Markdown 功能更强大，且不失轻便与灵活。

Sphinx 安装

Python安装

Python的安装非常简单，在官网下载对应系统版本的Python：https://www.python.org/downloads/
，按官方安装文档步骤即可。

Sphinx安装

Sphinx的安装非常简单，在系统安装好 Python 的情况下直接使用 pip
来安装（Sphinx同时支持Py2和Py3）。

1

pip install Sphinx

Sphinx 简单使用

Sphinx 有一个 sphinx-quickstart
 命令可以让我们很方便的从零开始创建一个 Sphinx 文档项目。sphinx-quickstart
 命令执行后会问我们一些项目相关的问题，按提示输入即可。这里推荐选择 imgmath: include math, rendered as PNG or SVG images，因为很多时候生成的文档很有可能是在内网访问，而 mathjax 会在互联网上下载渲染数据公式的JS脚本，很影响加载时间或造成根本就下载不下来。

Sphinx 文档项目创建好后，目录结构如下：

1
2
3
4
5
6
7
8
9
10
11

.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
4 directories, 4 files

对于 Sphinx 的使用教程，网上有很多。这里推荐一些：

• 使用 sphinx 制作简洁而又美观的文档

• Sphinx 使用手册

• 用Sphinx编写技术文档

• 写最好的文档：Sphinx + Read the Docs

关于中文

Sphinx是通过latex来生成PDF的，所以要解决PDF中文乱码问题就要从latex着手。作者使用了Google Noto字体，这个字体在现代Linux系统都可以从源直接安装，Windows/Mac 系统用户请从 Google Noto 字体官方寻找安装手册。修改 source/conf.py
 文件的 latex_elements
配置的 preamble
 选项如下：

1
2
3
4
5
6
7
8
9
10
11

'preamble': '''
\\usepackage{xeCJK}
\\usepackage{indentfirst}
\\setlength{\\parindent}{2em}
\\setCJKmainfont{Noto Serif CJK SC}
\\setCJKmonofont[Scale=0.9]{Noto Sans Mono CJK SC}
\\setCJKfamilyfont{song}{Noto Sans CJK SC}
\\setCJKfamilyfont{sf}{Noto Sans CJK SC}
'''
使用如下步骤编译PDF文件（注意：这里需要运行两次`xelatex *.tex` 才能生成正常的带目录索引的PDF文档）：

make latex
cd build/latex/
xelatex .tex
xelatex .tex
```

生成的PDF文件名为： sphinx.pdf。

xelatex 需要安装 texlive，注意：不要使用Linux源里的texlive，一定要使用官方的发行版（DVD）。下载地址：http://mirrors.ustc.edu.cn/CTAN/systems/texlive/Images/ 。

总结

最后，我写了一个Sphinx文档模板 Sphinx 文档起步，放在Github上。

https://github.com/yangbajing/sphinx-doc-starter。这是一个配置好的支持生成中文PDF 的Sphinx文档项目模板，朋友们可以这个项目做为起步，一步一步构建自己的Sphinx电子文档。