Merge branch 'doc/language_link' into 'master'

docs: add language link to easily change to Chinese version.

See merge request idf/esp-idf!2051
This commit is contained in:
Angus Gratton 2018-05-21 11:00:37 +08:00
commit 9802c3e32c
29 changed files with 96 additions and 5 deletions

BIN
docs/_static/choose_version.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

View file

@ -165,6 +165,20 @@ How it renders:
A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``.
Linking Language Versions
-------------------------
Switching between documentation in different languages may be done using ``:link_to_translation:`` custom role. The role placed on a page of documentation provides a link to the same page in a language specified as a parameter. Examples below show how to enter links to Chinese and English versions of documentation::
:link_to_translation:`zh_CN:中文版`
:link_to_translation:`en:English`
The language is specified using standard abbreviations like ``en`` or ``zh_CN``. The text after last semicolon is not standardized and may be entered depending on the context where the link is placed, e.g.::
:link_to_translation:`en:see description in English`
.. _add-illustrations:
Add Illustrations

View file

@ -1,5 +1,6 @@
Add IDF_PATH to User Profile
============================
:link_to_translation:`zh_CN:[中文]`
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.

View file

@ -1,6 +1,7 @@
**********************
Eclipse IDE on Windows
**********************
:link_to_translation:`zh_CN:[中文]`
Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.

View file

@ -1,6 +1,7 @@
********************************
Build and Flash with Eclipse IDE
********************************
:link_to_translation:`zh_CN:[中文]`
.. _eclipse-install-steps:

View file

@ -1,5 +1,6 @@
Establish Serial Connection with ESP32
======================================
:link_to_translation:`zh_CN:[中文]`
This section provides guidance how to establish serial connection between ESP32 and PC.

View file

@ -1,5 +1,6 @@
ESP32-PICO-KIT V4 Getting Started Guide
=======================================
:link_to_translation:`zh_CN:[中文]`
This user guide shows how to get started with the ESP32-PICO-KIT V4 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.

View file

@ -1,6 +1,7 @@
***********
IDF Monitor
***********
:link_to_translation:`zh_CN:[中文]`
The IDF Monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.

View file

@ -1,6 +1,7 @@
***********
Get Started
***********
:link_to_translation:`zh_CN:[中文]`
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.

View file

@ -1,6 +1,7 @@
*************************************
Standard Setup of Toolchain for Linux
*************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites

View file

@ -1,6 +1,7 @@
**************************************
Standard Setup of Toolchain for Mac OS
**************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites
=====================

View file

@ -1,5 +1,6 @@
Build and Flash with Make
=========================
:link_to_translation:`zh_CN:[中文]`
Finding a project

View file

@ -1,6 +1,7 @@
***************************************
Standard Setup of Toolchain for Windows
***************************************
:link_to_translation:`zh_CN:[中文]`
Introduction
============

View file

@ -1,8 +1,11 @@
ESP-IDF Programming Guide
=========================
:link_to_translation:`zh_CN:[中文]`
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
The documentation has different language versions (:link_to_translation:`en:English`, :link_to_translation:`zh_CN:中文版`, :doc:`How to switch between languages? <languages>`). However, please refer to the English version if there is any discrepancy.
================== ================== ==================
|Get Started|_ |API Reference|_ |H/W Reference|_
------------------ ------------------ ------------------
@ -44,5 +47,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
Resources <resources>
Copyrights <COPYRIGHT>
About <about>
[语言/Languages] <languages>
* :ref:`genindex`

19
docs/en/languages.rst Normal file
View file

@ -0,0 +1,19 @@
Switch Between Languages/切换语言
=================================
The documentation now has two language versions, however, please refer to the English version if there is any discrepancy.
本文档现在有两种语言的版本,如有出入请以英文版本为准。
- English/英文
- Chinese/中文
You can easily changed from one language to another by the panel on the sidebar like below. Just click on the **Read
the Docs** title button on the left-bottom conner if it is folded.
如下图所示,你可使用边栏的面板进行语言的切换。如果该面板被折叠,点击左下角 **Read the Docs** 标题按钮来显示它。
.. image:: /../_static/choose_version.png

View file

@ -1,6 +1,7 @@
# based on http://protips.readthedocs.io/link-roles.html
import re
import os
from docutils import nodes
from local_util import run_cmd_get_output
@ -13,10 +14,11 @@ def get_github_rev():
path = tag
return path
def setup(app):
baseurl = 'https://github.com/espressif/esp-idf'
rev = get_github_rev()
# links to files or folders on the GitHub
baseurl = 'https://github.com/espressif/esp-idf'
app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev)))
app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
@ -27,6 +29,19 @@ def setup(app):
app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev)))
app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev)))
# link to the current documentation file in specific language version
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
# provide RTD specific commit identification to be included in the link
tag_rev = 'latest'
if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
tag_rev = rev
else:
# if not on the RTD then provide generic identification
tag_rev = run_cmd_get_output('git describe --always')
app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
def autolink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
m = re.search('(.*)\s*<(.*)>', text)
@ -40,3 +55,14 @@ def autolink(pattern):
node = nodes.reference(rawtext, link_text, refuri=url, **options)
return [node], []
return role
def crosslink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
(language, link_text) = text.split(':')
docname = inliner.document.settings.env.docname
doc_path = inliner.document.settings.env.doc2path(docname, None, None)
return_path = '../' * doc_path.count('/')
url = pattern % (return_path, language, docname)
node = nodes.reference(rawtext, link_text, refuri=url, **options)
return [node], []
return role

View file

@ -1,5 +1,6 @@
在用户配置文件中添加 IDF_PATH
==============================
:link_to_translation:`en:[English]`
为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置,请按照以下说明将其添加到用户配置文件中。

View file

@ -1,6 +1,7 @@
*****************************************************
Eclipse IDE 的创建和烧录指南Windows 平台)
*****************************************************
:link_to_translation:`en:[English]`
Windows 平台上的 Eclipse 配置略有不同,具体步骤请见下文。

View file

@ -1,6 +1,7 @@
****************************
Eclipse IDE 的创建和烧录指南
****************************
:link_to_translation:`en:[English]`
.. _eclipse-install-steps:

View file

@ -1,5 +1,6 @@
与 ESP32 创建串口连接
=========================
:link_to_translation:`en:[English]`
本章节介绍如何在 ESP32 和 PC 之间建立串口连接。

View file

@ -1,5 +1,6 @@
ESP32-PICO-KIT V4 入门指南
============================
:link_to_translation:`en:[English]`
本指南介绍了如何开始使用 ESP32-PICO-KIT V4 迷你开发板。有关 ESP32-PICO-KIT 其他版本的介绍,请见 :doc:`../hw-reference/index`

View file

@ -1,6 +1,7 @@
***********
IDF Monitor
***********
:link_to_translation:`en:[English]`
IDF Monitor 工具是在 IDF 中调用 “make monitor” 目标时运行的 Python 程序。

View file

@ -1,6 +1,7 @@
***********
快速入门
***********
:link_to_translation:`en:[English]`
本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework),包括配置、编译、下载固件到开发板等步骤。

View file

@ -1,6 +1,7 @@
*****************************
Linux 平台工具链的标准设置
*****************************
:link_to_translation:`en:[English]`
安装前提
=====================

View file

@ -1,6 +1,7 @@
**************************************
在 Mac OS 上安装 ESP32 工具链
**************************************
:link_to_translation:`en:[English]`
安装准备
================

View file

@ -1,5 +1,6 @@
通过 make 指令创建和烧录项目
=============================
:link_to_translation:`en:[English]`
寻找项目

View file

@ -1,6 +1,7 @@
***************************************
Windows 平台工具链的标准设置
***************************************
:link_to_translation:`en:[English]`
引言
============

View file

@ -1,8 +1,11 @@
ESP-IDF 编程指南
=========================
:link_to_translation:`en:[English]`
这是乐鑫 IoT 开发开发框架 (`esp-idf <https://github.com/espressif/esp-idf>`_) 的文档. ESP-IDF 是 `ESP32 <https://www.espressif.com/zh-hans/products/hardware/esp32/overview>`_ 芯片的官方开发框架.
本文档提供不同语言的翻译版本 (:link_to_translation:`en:English`, :link_to_translation:`zh_CN:中文版`, :doc:`如何切换语言? <languages>`), 如有出入请以英文版本为准。
================== ================== ==================
|快速入门|_ |API 参考|_ |H/W 参考|_
------------------ ------------------ ------------------
@ -44,5 +47,7 @@ ESP-IDF 编程指南
相关资源 <resources>
版权 <COPYRIGHT>
关于 <about>
[Languages/语言] <languages>
* :ref:`genindex`

1
docs/zh_CN/languages.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../en/languages.rst