readthedocs网托管持多语言文档
希望在readthedocs上创建支持多语言的文档,效果类似:
通过语言选项,可以切到到不同的语言版本;实现这个目标包含两个主要步骤:
- 在本地对文档进行翻译
- 在
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目录是其文档目录。
开始操作:
- 创建一个新项目
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
- 配置新项目中的
conf.py
language = 'zh_CN' # 设置新项目的语言与中文
locale_dirs = ['locale/'] # 设置本地化数据目录
- 然后在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忽略上传。
- 构建中文文档
在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
- 将
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/就可以选择语言了。
参考文档
- 建议一读:http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
- 比较简陋的readthedocs官方文档:https://docs.readthedocs.io/en/stable/localization.html
readthedocs网托管持多语言文档的更多相关文章
- KOTLIN开发语言文档(官方文档) -- 入门
网页链接:https://kotlinlang.org/docs/reference/basic-syntax.html 1. 入门 1.1. 基本语法 1.1.1. 定义包 包说明应该在源 ...
- 多国语言文档识别 ABBYY FineReader Corporate v12.0.101.388.7z 绿色破解版
ABBYY 是一家俄罗斯软件公司,在文档识别,数据捕获和语言技术的开发中居世界领先地位.其获奖产品 FineReader OCR 软件可以把静态纸文件和 PDF 文件转换成可管理的电子数据,可以大大节 ...
- 怎么让OCR文字识别软件转换别的语言文档
ABBYY PDF Transformer+让您可创建或转换希伯来语.意第绪语.日语.中文.泰语.韩语和阿拉伯语的文档.那么如何顺利使用这些复杂语言文字呢?小编教你两步骤轻松快速处理包含以下复杂语言文 ...
- Kotlin开发语言文档(官方文档)-- 目录
开始阅读Kotlin官方文档.先上文档目录.有些内容还未阅读,有些目录标目翻译还需琢磨琢磨.后续再将具体内容的链接逐步加上. 文档链接:https://kotlinlang.org/docs/kotl ...
- DXperience-12.1.5 官网下载+注册破解+帮助文档
安装包 DXperience 12.1.5 Universal 帮助文档: DXperienceHelp2010 DXperienceHelp2010-12.1.5.exe DXperienceHel ...
- KOTLIN开发语言文档(官方文档) -- 2.基本概念
网页链接:https://kotlinlang.org/docs/reference/basic-types.html 2. 基本概念 2.1. 基本类型 从可以在任何变量处理调用成员函数和属性 ...
- 使用sphinx制作接口文档并托管到readthedocs
此sphinx可不是彼sphinx,此篇是指生成文档的工具,是python下最流行的文档生成工具,python官方文档即是它生成,官方网站是http://www.sphinx-doc.org,这里是一 ...
- Hortonworks官网文档怎么找?
Hortonworks官网文档怎么找? 作者:尹正杰 版权声明:原创作品,谢绝转载!否则将追究法律责任. 俗话说,授人予鱼不如授人予渔,网上部署HDP的部署方式的博客有很多,看得你是眼花缭乱的.其实万 ...
- 使用gitlab runner 进行CI(四):使用Gitlab Page托管项目文档
目录 1.什么是Gitlab Pages 2.开启Gitlab Pages 3.基本过程 4.托管markdown文档 4.1 安装sphinx等依赖 4.2 配置项目的sphinx配置 4.3 编写 ...
随机推荐
- 复制图片链接和标题生成Markdown文本
写Markdown的时候常常会需要复制图片链接和标题以插入图片,不借助其他工具的话,一般需要先在Markdown文件中输入插入图片的格式,然后在浏览器中复制图片链接和标题将其依次粘贴到Markdown ...
- 【Python】2.12学习笔记 变量
变量 关于变量我有一个不能理解的,关于全局变量作用域与地址的问题,学函数的时候我可能会搞懂它并且写下来 另外,其实昨天说的是有些不准确的,\(Python\)里的变量不是不用声明类型,只是声明方式特殊 ...
- Android微信逆向--实现发朋友圈动态
0x0 前言 最近一直在研究Windows逆向的东西,想着快要把Android给遗忘了.所以就想利用工作之余来研究Android相关的技术,来保持对Android热情.调用微信代码来发送朋友圈动态一直 ...
- keep-alive 必须 页面有name 要不缓存不住数据
keep-alive 必须 页面有name 要不缓存不住数据
- mysql5.7 ERROR 1045 (28000): Access denied for user解决方法
https://blog.csdn.net/csy2961903/article/details/51345401 参考此文注意指名数据库mysql.user
- Fluent算例精选|02瞬态滑移网格分析叶轮机械内部流动
本算例使用的软件:fluent.icem 通过学习本算例您将获得? 1.学会周期区域创建 2.学会瞬态求解器及滑移网格边界条件设置 3.学会周期面.滑移面设置 4.学会如何监测压力脉动(声学仿真) 5 ...
- window 查看端口 杀端口
最近写项目,总是出现端口被占用的问题,原来傻傻的把电脑重启一下,终于有一天受不了了,想要想办法解决.刚开始从网上找了好多教程,发现不行.开始自己尝试,终于,成功的将占用端口的进程杀掉.在此记录下过程( ...
- 手把手教你用GoEasy实现Websocket IM聊天
经常有朋友问起GoEasy如何实现IM,今天就手把手的带大家从头到尾用GoEasy实现一个完整IM聊天,全套代码已经放在了github. 今日的前端技术发展可谓百花争鸣,为了确保本文能帮助到使用任何技 ...
- [CVPR 2019]Normalized Object Coordinate Space for Category-Level 6D Object Pose and Size Estimation
论文地址:https://arxiv.org/abs/1901.02970 github链接:https://github.com/hughw19/NOCS_CVPR2019 类别级6D物体位姿 ...
- Spring----注释----开启Annotation <context:annotation-config> 和 <context:component-scan>诠释及区别
来源:http://www.cnblogs.com/leiOOlei/p/3713989.html <context:annotation-config> 和 <context:co ...