生成 Django 中文文档 PDF 版

Posted on | In ,

本文档描述了使用 Sphinx 生成 Django 中文文档 PDF 版本的步骤。

主要包括：克隆 Django 及其翻译仓库、配置 Sphinx 支持中文及 PDF 输出、设置翻译环境和生成 LaTeX 文件、安装 MikTeX 并生成 PDF 文档。

此外，文档还提及可以使用 Sphinx 在本地生成 HTML 格式的文档。

克隆 Django 文档和翻译仓库

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

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

切换到需要的版本的分支

1
2
3
4
# django-docs-translations
git checkout stable/4.2.x
# django
git checkout stable/4.2.x

安装第三方库

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

配置 conf.py

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 设置语言
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 目录中。

1
sphinx-build -b gettext . _build/gettext

运行 sphinx-intl update

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

1
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命令行）：

1
2
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：

1
2
3
4
5
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 没有书签。

generate_django_pdf1

sphinx 生成文档

也能在本地生成文档。

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

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

generate_django_pdf2

0%