生成 Django 中文文档 PDF 版

背景

浏览看到一个帖子，有个评论说可以用 sphinx 构建一个 pdf，正好最近用到了 sphinx，于是试了下，最终构建了一个关于 Django 官方文档的中文版 PDF 文件。

克隆 Django 文档和翻译仓库

打开命令行，执行以下命令克隆仓库：

git clone https://github.com/django/django.git
git clone https://github.com/django/django-docs-translations.git

切换到需要的版本的分支

# django-docs-translations
git checkout stable/4.2.x
# django
git checkout stable/4.2.x

安装第三方库

pip install sphinx sphinx-rtd-theme sphinx-intl  # 用于安装 Sphinx 和多语言支持
pip install -U sphinx_rtd_theme recommonmark latexmk  # 用于生成 PDF 所需的依赖

配置 conf.py

在 django/docs/conf.py 中添加或修改以下配置来启用中文翻译：

# 设置语言
language = 'zh_CN'

# 加入 PDF 输出格式
latex_engine = 'xelatex'
latex_elements = {
    "fontpkg": r"""
        \setmainfont{Symbola}
    """,
    "preamble": r"""
        \usepackage{newunicodechar}
        \usepackage[UTF8]{ctex}
        \newunicodechar{π}{\ensuremath{\pi}}
        \newunicodechar{≤}{\ensuremath{\le}}
        \newunicodechar{≥}{\ensuremath{\ge}}
        \newunicodechar{♥}{\ensuremath{\heartsuit}}
        \newunicodechar{…}{\ensuremath{\ldots}}
        \usepackage{ctex}  % 中文支持
        \usepackage{fontspec}  % 字体支持
        \setmainfont{Times New Roman}  % 英文主字体
        \setsansfont{Arial}  % 英文无衬线字体
        \setmonofont{Courier New}  % 英文等宽字体
        \setCJKmainfont{SimSun}  % 中文字体
    """,
}

# Sphinx theme，可以不改
html_theme = "sphinx_rtd_theme"

设置和同步翻译

进入 django/docs 目录，用 sphinx-intl 设置语言环境。在生成多语言支持的翻译文件时，Sphinx 首先需要生成 .pot 文件。

生成 .pot 文件

在 django/docs 目录中运行以下命令，会将所有可翻译的文本提取为 .pot 文件，并放在 _build/gettext 目录中。

sphinx-build -b gettext . _build/gettext

运行 sphinx-intl update

在生成 .pot 文件后，接着运行 sphinx-intl update 命令，这一步将根据 .pot 文件创建或更新 zh_CN 语言的 .po 文件，这里是在 doc 目录下创建了 locale/zh_CN\LC_MESSAGES，并生成了一些后缀是po的文件。

sphinx-intl update -p _build/gettext -l zh_CN

复制翻译文件

将 django-docs-translations/zh_Hans/LC_MESSAGES 下的 .po 文件复制到 django/docs/locale/zh_CN/LC_MESSAGES，替换掉相应的 .po 文件。

构建 PDF

生成 tex 文件

在 django/docs 目录中运行以下命令生成 tex 文件（这里是在windows命令行）：

sphinx-intl build
make.bat latex

成功后，这会在 _build/latex 文件夹中生成一个 django.tex 文件。

安装 MikTeX

安装 MikTeX 或 TeX Live 作为 LaTeX 引擎，用于生成 PDF。

我尝试下载 MikTeX下载_latex文本编辑器最新64位版v21.8_3DM软件 (3dmgame.com)，安装目录是 D:\Program Files\MiKTeX。

生成 PDF

在 django\docs\_build\latex 目录下，执行生成 pdf：

cd _build/latex
"D:\Program Files\MiKTeX\miktex\bin\x64\lualatex" -interaction=nonstopmode django.tex

# "D:\Program Files\MiKTeX\miktex\bin\x64\pdflatex" django.tex  # 有报错，没搞成
# "D:\Program Files\MiKTeX\miktex\bin\x64\xelatex" -interaction=nonstopmode django.tex  # 书签没有标题

最后生成了如下 pdf。期间试了好几个方法，不是编译报错，就是生成了空白的 pdf，或者生成的 pdf 没有书签。

Sphinx 生成文档

也能在本地生成文档。

sphinx-build -b html . _build/html -D html_theme=sphinx_rtd_theme

进入 docs/_build/html，通过浏览器打开 index.html，看到文档。