[Python开发] sphinx学习

Sphinx是一个python文档生成器，详见：http://www.sphinx-doc.org/en/stable/

安装Sphinx。

pip install sphinx

配置文档资源

使用Sphinx的向导quickstart自动生成默认的conf.py。

sphinx-quickstart

生成

sphinx-build -b html sourcedir builddir

如果在向导时候创建了Makefile和make.bat，则可以使用更简单的命令。

make html

国际化

安装sphinx-intl

pip install sphinx-intl

添加配置到conf.py中

locale_dirs = ['locale/']
gettext_compact = False

提取文档翻译信息

sphinx-build -b gettext sourcedir builddir/locale

如果make.bat中有相应的命令的话也可以用

make gettext

在_build/local/生成.pot文件。

安装/更新locale_dir

根据_build/locale在当前目录生成locale/文件夹，里面有待翻译的文件。如下语言为zh，生成locale/zh/LC_MESSAGES/文件夹，里面有待翻译的po文件。

sphinx-intl update -p _build/locale -l zh

翻译po文件

在msgstr所在行写入上一行msgid所对应的翻译内容，如

msgid "Hello World!"
msgstr "你好，世界！"

生成mo文件及相应的html

sphinx-build -D language=zh -b html sourcedir builddir/html-zh

在po文件所在位置生成相应的mo文件，并在builddir/html-zh/中生成相应的html。