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” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。
 
@@ -60,4 +61,4 @@ Linux and MacOS
 
     export IDF_PATH=~/esp/esp-idf
 
-如果您从 :ref:`get-started-setup-path` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project` 小节。
+如果您从 :ref:`get-started-setup-path` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project` 小节。

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

@@ -1,6 +1,7 @@
 *****************************************************
 Eclipse IDE 的创建和烧录指南（Windows 平台）
 *****************************************************
+:link_to_translation:`en:[English]`
 
 Windows 平台上的 Eclipse 配置略有不同，具体步骤请见下文。
 
@@ -78,4 +79,4 @@ Windows 平台的 Eclipse 介绍到此结束，下方将主要将介绍一些关
 * 首先，xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链，但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于：msys2 需要使用 Cygwin，并支持 Unix 风格的路径，即 ``/c/blah``，而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是，``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能，其内置 “include” 目录全部位于 ``/usr/`` 路径下，这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 风格路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器，可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。
 
 
-* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 Eclipse 的结果。
+* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 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`。
 
@@ -216,4 +217,4 @@ Header J3
 .. toctree::
     :hidden:
 
-    get-started-pico-kit-v3	
+    get-started-pico-kit-v3	

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