Merge branch 'doc/language_link' into 'master'

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

See merge request idf/esp-idf!2051

docs/en/contribute/documenting-code.rst

@@ -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

docs/en/get-started/add-idf_path-to-profile.rst

@@ -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.
 

docs/en/get-started/eclipse-setup-windows.rst

@@ -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.
 

docs/en/get-started/eclipse-setup.rst

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

docs/en/get-started/establish-serial-connection.rst

@@ -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.
 

docs/en/get-started/get-started-pico-kit.rst

@@ -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`.
 

docs/en/get-started/idf-monitor.rst

@@ -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.
 

docs/en/get-started/index.rst

@@ -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. 
 

docs/en/get-started/linux-setup.rst

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

docs/en/get-started/macos-setup.rst

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

docs/en/get-started/make-project.rst

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

docs/en/get-started/windows-setup.rst

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

docs/en/index.rst

@@ -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`

docs/en/languages.rst

@@ -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
+
+
+

docs/link-roles.py

@@ -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

docs/zh_CN/get-started/add-idf_path-to-profile.rst

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

docs/zh_CN/get-started/eclipse-setup-windows.rst

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

docs/zh_CN/get-started/eclipse-setup.rst

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

docs/zh_CN/get-started/establish-serial-connection.rst

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

docs/zh_CN/get-started/get-started-pico-kit.rst

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

docs/zh_CN/get-started/idf-monitor.rst

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

docs/zh_CN/get-started/index.rst

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

docs/zh_CN/get-started/linux-setup.rst

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

docs/zh_CN/get-started/macos-setup.rst

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

docs/zh_CN/get-started/make-project.rst

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

docs/zh_CN/get-started/windows-setup.rst

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

docs/zh_CN/index.rst

@@ -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`

docs/zh_CN/languages.rst

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