readthedocs web hosting multilingual documentation

I hope to create multi-language documents on readthedocs with similar effects:

Through language options, you can switch to different language versions; achieving this goal involves two main steps:

Translate documents locally
In the readthedocs.orgconfiguration on the translation

This article assumes that you already have some knowledge of sphinxdocument generation tools and readthedocs.orgdocument hosting websites. This article focuses on multi-language configuration.

Translate documents locally

Some packages need to be installed before translation:

sphinx: document generation tool
sphinx_intl: multilingual tool
recommonmark: sphinx support markdown plugin
sphinx_rtd_theme: readthedocs theme plugin for sphinx

Installation command:

pip install sphinx sphinx_intl recommonmark sphinx_rtd_theme

We now have a project, and its documentation is in English, and the English documentation has been deployed on the readthedocs website; taking deptables as an example, its .readthedocs.ymlfile content is:

version: 2

sphinx:
  configuration: docs/source/conf.py

formats: all

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

docs/source/conf.py The content is:

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'),
]

The structure of the directory after the source code is reduced:

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

Document access address:
http://deeptables.readthedocs.io/
where the docs directory is its documentation directory.
Start operation:

Create a new project deeptables-docs-zh_CNand copy the original project docs

➜  mkdir deeptables-docs-zh_CN
➜  cp -r  deeptables/docs deeptables-docs-zh_CN
➜  cp deeptables/.readthedocs.yml deeptables-docs-zh_CN

Configure in the new projectconf.py

language = 'zh_CN'  # 设置新项目的语言与中文
locale_dirs = ['locale/']  # 设置本地化数据目录

Then execute the command in the source directory to generate the pot file

➜  cd source
➜  sphinx-build -b gettext . locale
正在运行 Sphinx v3.0.0
正在加载翻译 [zh_CN]... 完成
创建输出目录... 完成
...

If you get an error and cannot find the module in the project, you can add your own project to PYTHONPATH:

export PYTHONPATH=/path/to/module

Under normal circumstances, a locale directory will be generated, which contains many pot files:

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

Then generate the po file that we need to edit:

➜ 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

Open the index.po file for translation:

# 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 <[email protected]>\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 "快速开始"

Where msgid is the content we want to translate, and msgstr is the translation result, for example, Quick-Starttranslate into 快速开始:

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

The relationship between po, pot, and mo files is as follows:

In order to generate a po file that we can manually write, we need to first generate a pot file, which can be generated from the rst / markdown file.
The generated po file can be formatted as a mo file, and finally combined with the initial rst / markdown file to generate translated html.
So readthedocs only needs rst / md and po files to build html, we can ignore other files through gitignore upload.

Build Chinese documents and
execute make html in the docs directory:

➜  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

Then we check the effect of starting the web service in the generated html directory:

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

Visit http: // localhost: 8000 / quick_start.html to see the effect.
The above steps can refer to the official sphinx documentation:
http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

It will be deeptables-docs-zh_CNplaced in git for maintenance, which is convenient for later posting on the rtd website.

In the `readthedocs.org`configuration on the translation

After the configuration in the previous chapter, we should have two project documents in different languages, and then we will integrate these two documents into a domain name.
readthedocs.orgThe method to support multiple languages is to configure multiple items.
You need to create a project on rtd first deeptables-docs-zh_CN. The project list of rtd is as follows:

Then configure the language of the new project to Chinese:

Please properly configure its git address and other information.
Please note here that configuration in conf.py is lnguage=zh_CNuseless and needs to be configured on the page. Then you can build a project to verify whether the document is in Chinese:
ttps: //deeptables.readthedocs.io/zh_CN/latest/
as shown:

Then we can configure our main document project to associate this translation document.
Find the translation option in the settings of the main document deeptables project, and then add the project deeptables-docs-zh_CN:

finally return to the main document https://deeptables.readthedocs.io/zh_CN/latest/ to select the language.

Reference documents

Suggested reading: http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
The relatively simple official document of readthedocs: https://docs.readthedocs.io/en/stable/localization.html