使用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是通过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电子文档。