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

2. 配置新項目中的conf.py

language = 'zh_CN'  # 設置新項目的語言與中文
locale_dirs = ['locale/']  # 設置本地化數據目錄

3. 然后在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 <[e-mail]>\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忽略上傳。

4. 構建中文文檔
   在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

5. 將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. 重新構建文檔
   重新配置翻譯后不是立即生效，需要重新再構建一下。

參考文檔

• http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
• readthedocs官方文檔：https://docs.readthedocs.io/en/stable/localization.html