1. fork scikit-learn
  2. 配置中文翻译环境
    1. 添加配置到conf.py中
    2. 添加make选项
    3. 修复gen_rst.py的bug
    4. 修复Sphinx-1.3.5中gettext.py的问题
  3. 翻译
    1. 准备翻译文件
    2. 翻译po文件
  4. 生成html并传到gh-pages
    1. 生成html
    2. 首次上传
    3. 以后更新
  5. 自定义

scikit-learn文档中文翻译：http://lijiancheng0614.github.io/scikit-learn/

scikit-learn是一个基于Python语言的机器学习工具。

源代码在https://github.com/scikit-learn/scikit-learn

目前稳定的版本是0.17，打算一边学习一边翻译文档：http://scikit-learn.org/0.17/index.html

fork scikit-learn

由于scikit-learn在github上公开了源代码，故只需fork就可以进行开发了。

我fork下来在 https://github.com/lijiancheng0614/scikit-learn ，并新建一个branch叫0.17.X-doc-zh，生成的文档放在gh-pages中，因此可以在 http://lijiancheng0614.github.io/scikit-learn/ 看到中文版的文档。

配置中文翻译环境

添加配置到conf.py中

1
2
locale_dirs = ['locale/']
gettext_compact = False

添加make选项

1
2
echo.  gettext   to make PO message catalogs
echo.  html-zh   to make standalone HTML files in Chinese
1
2
3
4
5
6
7
8
9
10
11
12
13
14
if "%1" == "gettext" (
    %SPHINXBUILD% -b gettext %ALLSPHINXOPTS% %BUILDDIR%/locale
    if errorlevel 1 exit /b 1
    echo.
    echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
    goto end
)

if "%1" == "html-zh" (
    %SPHINXBUILD% -D language=zh -b html %ALLSPHINXOPTS% %BUILDDIR%/html-zh
    echo.
    echo.Build finished. The HTML pages are in %BUILDDIR%/html-zh.
    goto end
)

修复gen_rst.py的bug

把with open(url, 'r') as fid:改为with open(url, 'r', encoding='utf-8') as fid:。

修复Sphinx-1.3.5中gettext.py的问题

不知道是不是doc和Sphinx的兼容性问题，我这里需要修改gettext.py来处理传入参数类型不对的问题：

由于source的类型可能为docutils.statemachine.StringList，故把

1
2
3
pofile.write("#: %s\n" % "\n#: ".join(
    "%s:%s" % (safe_relpath(source, self.outdir), line)
    for source, line, _ in positions))

改为

1
2
3
pofile.write("#: %s\n" % "\n#: ".join(
    "%s:%s" % (safe_relpath(source, self.outdir) if isinstance(source, str) else '', line)
    for source, line, _ in positions))

翻译

准备翻译文件

  • 提取文档翻译信息到_build/local/

    1
    make gettext

  • 生成po文件到locale/

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

翻译po文件

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

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

生成html并传到gh-pages

生成html

1
make html-zh

首次上传

这里把生成的html放在_build/html-zh中，并用git来版本控制，每次再fetch到外面的gh-pages的branch，然后上传到github上。

1
2
3
4
5
6
cd doc\_build\html-zh
git init
cd ..\..\..\
git fetch doc\_build\html-zh
git checkout -b gh-pages FETCH_HEAD
git push -u origin gh-pages

以后更新

只需在_build/html-zh中commit，然后fetch到外面的gh-pages的branch，再上传到github上。

1
2
git fetch doc\_build\html-zh :gh-pages
git push -u origin gh-pages

自定义

在doc/themes/scikit-learn/layout.html中可以修改Github "fork me" ribbon和google_analytics信息。