readthedocs web hosting documentación multilingüe

Espero crear documentos en varios idiomas en readthedocs con efectos similares:

A través de las opciones de idioma, puede cambiar a diferentes versiones de idioma; lograr este objetivo implica dos pasos principales:

Traducir documentos localmente
En la readthedocs.orgconfiguración de la traducción

Este artículo asume que ya tiene algún conocimiento de sphinxlas herramientas de generación de documentos y readthedocs.orgsitios web de alojamiento de documentos, y se centra en la configuración en varios idiomas.

Traducir documentos localmente

Algunos paquetes deben instalarse antes de la traducción:

sphinx: herramienta de generación de documentos
sphinx_intl: herramienta multilingüe
recommonmark: plugin de reducción de compatibilidad con sphinx
sphinx_rtd_theme: complemento de tema readthedocs para sphinx

Comando de instalación:

pip install sphinx sphinx_intl recommonmark sphinx_rtd_theme

Ahora tenemos un proyecto, y su documentación está en inglés, y la documentación en inglés se ha implementado en el sitio web de readthedocs; tomando los archivos como ejemplo, .readthedocs.ymlel contenido de su archivo es:

version: 2

sphinx:
  configuration: docs/source/conf.py

formats: all

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

docs/source/conf.py El contenido es:

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

La estructura del directorio después de que se reduce el código fuente:

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

Dirección de acceso al documento:
http://deeptables.readthedocs.io/
donde el directorio docs es su directorio de documentación.
Iniciar operación:

Cree un nuevo proyecto deeptables-docs-zh_CNy copie los documentos originales del proyecto.

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

Configurar en el nuevo proyectoconf.py

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

Luego ejecute el comando en el directorio fuente para generar el archivo pot

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

Si obtiene un error y no puede encontrar el módulo en el proyecto, puede agregar su propio proyecto a PYTHONPATH:

export PYTHONPATH=/path/to/module

En circunstancias normales, se generará un directorio de configuración regional, que contiene muchos archivos pot:

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

Luego genera el archivo po que necesitamos editar:

➜ 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

Abra el archivo index.po para la traducción:

# 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 "快速开始"

Donde msgid es el contenido que queremos traducir, y msgstr es el resultado de la traducción, por ejemplo, Quick-Starttraduzca a 快速开始:

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

La relación entre los archivos po, pot y mo es la siguiente:

Para generar un archivo po que podamos escribir manualmente, primero debemos generar un archivo pot, que puede generarse a partir del primer archivo / markdown.
El archivo po generado puede formatearse como un archivo mo, y finalmente combinarse con el primer archivo inicial / markdown para generar html traducido.
Entonces, readthedocs solo necesita archivos primero / md y po para construir html, podemos ignorar otros archivos a través de la carga de gitignore.

Cree documentos chinos y
ejecute make html en el directorio docs:

➜  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

Luego verificamos el efecto de iniciar el servicio web en el directorio html generado:

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

Visite http: // localhost: 8000 / quick_start.html para ver el efecto.
Los pasos anteriores pueden hacer referencia a la documentación oficial de esfinge:
http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

Se deeptables-docs-zh_CNcolocará en git para mantenimiento, lo cual es conveniente para su posterior publicación en el sitio web de rtd.

En la `readthedocs.org`configuración de la traducción

Después de la configuración en el capítulo anterior, deberíamos tener dos documentos de proyecto en diferentes idiomas, y luego integraremos estos dos documentos en un nombre de dominio.
readthedocs.orgEl método para admitir múltiples idiomas es configurar múltiples elementos.
Primero debe crear un proyecto en rtd deeptables-docs-zh_CN. La lista de proyectos de rtd es la siguiente:

Luego configure el idioma del nuevo proyecto en chino:

Configure correctamente su dirección git y otra información.
Tenga en cuenta que la configuración en conf.py es lnguage=zh_CNinútil y debe configurarse en la página. Luego puede construir un proyecto para verificar si el documento está en chino:
ttps: //deeptables.readthedocs.io/zh_CN/latest/
como se muestra:

Luego podemos configurar nuestro proyecto de documento principal para asociar este documento de traducción.
Busque la opción de traducción en la configuración del proyecto de tablas profundas del documento principal y luego agregue el proyecto deeptables-docs-zh_CN:

finalmente regrese al documento principal https://deeptables.readthedocs.io/zh_CN/latest/ para seleccionar el idioma.

Documentos de referencia

Lectura sugerida: http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
El documento oficial relativamente simple de readthedocs: https://docs.readthedocs.io/en/stable/localization.html