readthedocs(RTD)托管持多语言文档

希望在readthedocs上创建支持多语言的文档，效果类似：

通过语言选项，可以切到到不同的语言版本；实现这个目标包含两个主要步骤：

  1. 在本地对文档进行翻译
  2. 在readthedocs.org上配置翻译

本文假设您已经对sphinx文档生成工具和readthedocs.org文档托管网站有所了解，本文主要专注于多语言的配置上。

在本地对文档进行翻译

翻译之前需要安装一些软件包：

  • sphinx: 文档生成工具
  • sphinx_intl: 多语言工具
  • recommonmark: sphinx支持markdown的插件
  • sphinx_rtd_theme: sphinx的readthedocs主题插件

安装命令：

pip install sphinx sphinx_intl recommonmark sphinx_rtd_theme

我们现在有一个项目了，并且其文档是英文的，并且英文文档已经部署到readthedocs网站上了;以deeptables为例，其.readthedocs.yml文件内容为：

version: 2

sphinx:
  configuration: docs/source/conf.py

formats: all

python:
  version: 3.6
  install:
    - requirements: docs/requirements.txt

docs/source/conf.py 的内容为：

import os, sys
sys.path.insert(0, os.path.abspath('..'))

project = 'DeepTables'
copyright = '2020, Zetyun.com'
author = 'Zetyun.com'

# The full version, including alpha/beta/rc tags
release = '0.1.1'
extensions = ['recommonmark',
              'sphinx.ext.autodoc',
              'sphinx.ext.napoleon',
              'sphinx.ext.viewcode'
              # 'sphinx.ext.autodoc',
              # 'sphinx.ext.mathjax',
              # 'sphinx.ext.ifconfig',
              # 'sphinx.ext.viewcode',
              # 'sphinx.ext.githubpages',
              ]
exclude_patterns = []
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
pygments_style = 'sphinx'
templates_path = ['_templates']
source_suffix = ['.rst', '.md']
master_doc = 'index'
html_static_path = ['_static']
language = 'en' # ['en', 'zh_CN']  #

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'deeptables', 'DeepTables Documentation',
     [author], 1)
]

texinfo_documents = [
    (master_doc, 'DeepTables', 'DeepTables Documentation',
     author, 'DeepTables', 'One line description of project.',
     'Miscellaneous'),
]

源码精简后的目录的结构：

├── deeptables
│   ├── __init__.py
├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   ├── requirements.txt
│   └── source
│       ├── conf.py
│       ├── index.rst
├── examples
├── requirements.txt
├── setup.cfg
├── setup.py
└── tests

文档访问地址:
http://deeptables.readthedocs.io/
其中docs目录是其文档目录。
开始操作：

  1. 创建一个新项目deeptables-docs-zh_CN，并把原来项目的docs复制过来
➜  mkdir deeptables-docs-zh_CN
➜  cp -r  deeptables/docs deeptables-docs-zh_CN
➜  cp deeptables/.readthedocs.yml deeptables-docs-zh_CN
  1. 配置新项目中的conf.py
language = 'zh_CN'  # 设置新项目的语言与中文
locale_dirs = ['locale/']  # 设置本地化数据目录
  1. 然后在source目录执行命令生成pot文件
➜  cd source
➜  sphinx-build -b gettext . locale
正在运行 Sphinx v3.0.0
正在加载翻译 [zh_CN]... 完成
创建输出目录... 完成
...

如果报错找不到项目里的模块，可以把自己的项目加入到PYTHONPATH中：

export PYTHONPATH=/path/to/module

正常情况下会生成locale目录，里面有很多pot文件：

➜  tree locale
locale
├── deeptables.datasets.pot
├── deeptables.eda.pot
├── deeptables.ensemble.pot
├── deeptables.fe.pot

然后生成我们需要编辑的po文件：

➜ sphinx-intl update -p locale -l zh_CN
Create: locale/zh_CN/LC_MESSAGES/model_config.po
Create: locale/zh_CN/LC_MESSAGES/deeptables.preprocessing.po
Create: locale/zh_CN/LC_MESSAGES/faq.po

打开index.po文件进行翻译：

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2020, Zetyun.com
# This file is distributed under the same license as the DeepTables package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2020.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: DeepTables \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2020-04-13 17:23+0800\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.8.0\n"

#: ../index.rst:62
msgid "Quick-Start"
msgstr "快速开始"

其中msgid是我们要翻译的内容，msgstr是翻译结果，比如把Quick-Start翻译成快速开始:

#: ../index.rst:62
msgid "Quick-Start"
msgstr "快速开始"

其中po,pot,mo文件的关系如图：

为了给我们生成可以人工编写的po文件，需要先生成pot文件，pot文件可以从rst/markdown文件生成。
生成的po文件可以格式化成mo文件，最终再结合最开始rst/markdown文件生成翻译后的html。
所以readthedocs进行构建生成html时仅需要rst/md和po文件，其他的文件我们可以通过gitignore忽略上传。

  1. 构建中文文档
    在docs目录执行make html:
➜  make clean
➜  make html
正在运行 Sphinx v3.0.0
正在加载翻译 [zh_CN]... 完成
创建输出目录... 完成
WARNING: html_static_path 指向的 '_static' 不存在
构建 [mo]： 1 个 po 文件的目标文件已过期
写入输出... [100%] locale/zh_CN/LC_MESSAGES/index.mo
...
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
build 成功, 111 warnings

然后我们在生成的html目录查看启动web服务查看效果：

(deeptables) ➜  docs cd build/html
(deeptables) ➜  html python3 -m http.server 8000

访问http://localhost:8000/quick_start.html查看效果。
以上步骤可以参考sphinx官方文档：
http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

  1. 将deeptables-docs-zh_CN放到git中维护，方便后面发布到rtd网站上。

在readthedocs.org上配置翻译

经过上一章的配置，我们应该拥有两个不同语言的项目文档，接着我们把这两个文档整合到一个域名上。
readthedocs.org支持多语言的方法是配置多个项目。
需要先在rtd在创建一个项目deeptables-docs-zh_CN，rtd的项目列表如下：

然后配置新项目的的语言为中文：

其git地址等其他信息请妥善配置。
此处请注意，在conf.py中配置lnguage=zh_CN没有用的，需要在页面上进行配置。接着可以构建一下项目，验证文档是否是中文的了：
ttps://deeptables.readthedocs.io/zh_CN/latest/
如图：

接着就可以配置我们的主文档项目关联这个翻译文档了。
在主文档deeptables项目的设置中找到翻译选项，然后把项目加入deeptables-docs-zh_CN：

最后返回主文档https://deeptables.readthedocs.io/zh_CN/latest/就可以选择语言了。

单个仓库托管多语言文档（推荐）

RTD支持设置sphinx配置文件的位置，多个RTD项目可以共用一个Git仓库，单个git仓库中建立多个sphinx项目，然后再与RTD的项目对应起来就可以：

  1. 中英文创建两个RTD的项目
    a. 分别设置其对应的语言（为了给英文项目设置翻译）

    b. 中文项目设置为英文项目的子项目（用处不大）

    c. 给英文项目设置翻译

    d. 在高级设置中分别设置sphinx配置文件的位置

  2. 重新构建文档
    重新配置翻译后不是立即生效，需要重新再构建一下。

参考文档

posted @ 2020-04-13 18:41  oaksharks  阅读(1725)  评论(0)  编辑  收藏  举报