Add translation for getting started guide - batch 1

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

@@ -1,3 +0,0 @@
-:orphan:
-
-.. Remove this file when the Chinese translation of getting started guide is updated

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

@@ -1,73 +0,0 @@
-在用户配置文件中添加 IDF_PATH 和 idf.py PATH
-==========================================================================================================
-
-:link_to_translation:`en:[英文]`
-
-使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量：
-
-- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径
-- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录
-
-为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。
-
-.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。
-
-.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。
-
-.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。
-
-.. _add-paths-to-profile-windows:
-
-Windows 操作系统
------------------------------------
-
-在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。
-
-在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。
-
-你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。
-
-- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。
-- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。
-
-如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
-
-
-.. _add-idf_path-to-profile-linux-macos:
-
-Linux 和 MacOS 操作系统
-------------------------------------
-
-要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中::
-
-    export IDF_PATH=~/esp/esp-idf
-    export PATH="$IDF_PATH/tools:$PATH"
-
-.. note::
-
-   ``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。
-
-请退出，并重新登录使更改生效。
-
-.. note::
-
-    并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。
-
-运行以下命令来检查 ``IDF_PATH`` 设置是否正确::
-
-    printenv IDF_PATH
-
-此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。
-
-为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令::
-
-  which idf.py
-
-这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。
-
-如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入::
-
-    export IDF_PATH=~/esp/esp-idf
-    export PATH="$IDF_PATH/tools:$PATH"
-
-如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。

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

@@ -4,6 +4,8 @@ Eclipse IDE 创建和烧录指南
 
 :link_to_translation:`en:[English]`
 
-有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。
+ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。
 
-.. _eclipse.org: https://www.eclipse.org/
+对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 `ESP-IDF Eclipse 插件 <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`。
+
+如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 </get-started-legacy/index>`，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 </get-started-legacy/eclipse-setup>` 章节。

docs/zh_CN/get-started/index.rst

@@ -1,22 +1,20 @@
-*******************
-快速入门（CMake）
-*******************
+***********
+快速入门
+***********
 
 :link_to_translation:`en:[English]`
 
-本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，
-
-通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
+本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
 
 .. include:: /_build/inc/version-note.inc
 
 概述
-====
+============
 
 ESP32 SoC 芯片支持以下功能：
 
 * 2.4 GHz Wi-Fi
-* 蓝牙 4.2 标准
+* 蓝牙 4.2
 * 高性能双核
 * 超低功耗协处理器
 * 多种外设
@@ -26,18 +24,18 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。
 
 准备工作
-========
+=============
 
 硬件：
 
 * 一款 **ESP32** 开发板
-* **USB 数据线** （USB A/Micro USB B）
+* **USB 数据线**  (A 转 Micro-B)
 * PC（Windows、Linux 或 Mac OS）
 
 软件：
 
 * 设置 **工具链**，用于编译 ESP32 代码；
-* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32  **应用程序**；
+* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
 * 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本；
 * 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse <https://www.eclipse.org/>`_。
 
@@ -51,7 +49,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 
 
 开发板简介
-==========
+===========================
 
 请点击下方连接，了解有关具体开发板的详细信息。
 
@@ -67,17 +65,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 .. _get-started-step-by-step:
 
 详细安装步骤
-==============
+=========================
 
 请根据下方详细步骤，完成安装过程。
 
 设置开发环境
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* :ref:`get-started-setup-toolchain`
+* :ref:`get-started-get-prerequisites` （:doc:`Windows <windows-setup>` 、:doc:`Linux <linux-setup>` 和 :doc:`macOS <macos-setup>`）
 * :ref:`get-started-get-esp-idf`
-* :ref:`get-started-setup-path`
-* :ref:`get-started-get-packages`
+* :ref:`get-started-set-up-tools`
+* :ref:`get-started-set-up-env`
 
 创建您的第一个工程
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -90,14 +88,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 * :ref:`get-started-build-monitor`
 
 
-.. _get-started-setup-toolchain:
+.. _get-started-get-prerequisites:
 
-第一步：设置工具链
-====================
+第一步：安装准备
+=============================
 
-工具链指一套用于编译代码和应用程序的程序。
-
-为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。
+在正式开始创建工程前，请先完成工具的安装，具体步骤见下：
 
 .. toctree::
     :hidden:
@@ -125,27 +121,22 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
 .. _Linux: ../get-started/linux-setup.html
 .. _Mac OS: ../get-started/macos-setup.html
 
-.. note::
-
-    在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
-
-此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置<get-started-customized-setup>` 章节获取更多信息。
-
-
 .. _get-started-get-esp-idf:
-.. _get-started-set-up-tools:
+
 
 第二步：获取 ESP-IDF
-===========================
+=================================
+
+在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
 
-除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
+获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。
 
-请将 ESP-IDF 下载到您的本地。
+.. note::
 
-获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
+    在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
 
 Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 打开终端，后运行以下命令：
 
@@ -156,71 +147,103 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
 
 Windows 操作系统
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。
+
+请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
 
-    较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
+除了使用 ESP-IDF 工具安装器，您也可以参考 :ref:`指南 <get-esp-idf-windows-command-line>` 手动下载 ESP-IDF。
 
-请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
+.. _get-started-set-up-tools:
 
-打开命令提示符，后运行以下命令：
+第三步：设置工具
+=================================
 
-.. include:: /_build/inc/git-clone-windows.inc
+除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。
 
-ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
+Windows 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
+请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。
 
-.. include:: /_build/inc/git-clone-notes.inc
+除了使用 ESP-IDF 工具安装器，您也可以通过 **命令提示符** 窗口手动安装这些工具。具体步骤见下：
 
-.. note::
+.. code-block:: batch
+
+    cd %userprofile%\esp\esp-idf
+    install.bat
+
+或使用 Windows PowerShell
+
+.. code-block:: powershell
+
+    cd ~/esp/esp-idf
+    ./install.ps1
+
+Linux 和 MacOS 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： :: 
+.. code-block:: bash
+
+    cd ~/esp/esp-idf
+    ./install.sh
+
+自定义工具安装路径
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，即 Linux 和 MacOS 系统中的 ``$HOME/.espressif`` 和 Windows 系统的 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。
 
-        cd esp-idf
-        git submodule update --init
+如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行“安装脚本” (``install.bat``、``install.ps1`` 或 ``install.sh``) 和导出脚本 (``export.bat``、``export.ps1`` 或 ``export.sh``) 均保持一致。
 
-.. _get-started-setup-path:
 .. _get-started-set-up-env:
 
-第三步：设置环境变量
-===========================
+第四步：设置环境变量
+=======================================
 
-请在您的 PC 上设置以下环境变量，否则无法编译工程。
+此时，您刚刚安装的工具尚未添加至 PATH 环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF 提供的另一个脚本完成。
 
-- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
-- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
+Windows 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
+Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开始”菜单创建一个 "ESP-IDF Command Prompt" 快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。
 
+此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码：
 
-.. _get-started-get-packages:
+.. code-block:: batch
 
-第四步：安装 Python 软件包
-=================================
+    %userprofile%\esp\esp-idf\export.bat
 
-ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
+或使用 Windows PowerShell
 
-    python -m pip install --user -r $IDF_PATH/requirements.txt
+.. code-block:: powershell
 
-.. note::
+    .$HOME/esp/esp-idf/export.ps1
+
+Linux 和 MacOS 操作系统
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令：
 
-    请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
+.. code-block:: bash
+
+    . $HOME/esp/esp-idf/export.sh
 
-    ``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
+注意，命令开始的 "." 与路径之间应有一个空格！
+
+此外，您也可以将这行代码增加至您的 ``.profile`` 或 ``.bash_profile`` 脚本中，这样您就可以在任何命令窗口使用 ESP-IDF 工具了。
 
 .. _get-started-start-project:
 
 第五步：开始创建工程
-=======================
+========================================
 
 现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
 
 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：
 
 Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -228,7 +251,7 @@ Linux 和 MacOS 操作系统
     cp -r $IDF_PATH/examples/get-started/hello_world .
 
 Windows 操作系统
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: batch
 
@@ -244,7 +267,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
 .. _get-started-connect:
 
 第六步：连接设备
-======================
+==========================================
 
 现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
 
@@ -264,34 +287,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
 .. _get-started-configure:
 
 第七步：配置
-=================
+=========================
 
 请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
 
 Linux 和 MacOS 操作系统
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
     cd ~/esp/hello_world
     idf.py menuconfig
 
-如果您的默认 Python 版本为 3.0 以上，可能需要运行  ``python2 idf.py`` 。
+如果您的默认 Python 版本为 3.0 及以上，可能需要运行 ``python2 $(which idf.py) menuconfig``。
 
 Windows 操作系统
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: batch
 
     cd %userprofile%\esp\hello_world
     idf.py menuconfig
 
-Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。
-
-.. note::
-
-    如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。
-
 如果之前的步骤都正确，则会显示下面的菜单：
 
 .. figure:: ../../_static/project-configuration.png
@@ -299,17 +316,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
     :alt: 工程配置 — 主窗口
     :figclass: align-center
 
-    工程配置 — 主窗口
+工程配置 — 主窗口
 
 ``menuconfig`` 工具的常见操作见下。
 
-* ``上下箭头``：移动
+* 上下箭头：移动
 * ``回车``：进入子菜单
 * ``ESC 键``：返回上级菜单或退出
 * ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
-* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
-* ``英文问号``：调出有关高亮选项的帮助菜单
-* ``/ 键``：寻找配置项目
+* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
+* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单
+* ``/ 键``：寻找配置工程
 
 .. attention::
 
@@ -318,7 +335,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 .. _get-started-build:
 
 第八步：编译工程
-==================
+=========================
 
 请使用以下命令，编译烧录工程：::
 
@@ -328,23 +345,23 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 
 .. code-block:: none
 
-   $ idf.py build
-   Running cmake in directory /path/to/hello_world/build
-   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
-   Warn about uninitialized values.
-   -- Found Git: /usr/bin/git (found version "2.17.0")
-   -- Building empty aws_iot component due to configuration
-   -- Component names: ...
-   -- Component paths: ...
-   
-   ... (more lines of build system output)
-   
-   [527/527] Generating hello-world.bin
-   esptool.py v2.3.1
-   
-   Project build complete. To flash, run this command:
-   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
-   or run 'idf.py -p PORT flash'
+    $ idf.py build
+    Running cmake in directory /path/to/hello_world/build
+    Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
+    Warn about uninitialized values.
+    -- Found Git:/usr/bin/git (found version "2.17.0")
+    -- Building empty aws_iot component due to configuration
+    -- Component names: ...
+    -- Component paths: ...
+
+    ... (more lines of build system output)
+
+    [527/527] Generating hello-world.bin
+    esptool.py v2.3.1
+
+    Project build complete. To flash, run this command:
+    ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
+    or run 'idf.py -p PORT flash'
 
 如果一切正常，编译完成后将生成 .bin 文件。
 
@@ -352,15 +369,15 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 .. _get-started-flash:
 
 第九步：烧录到设备
-====================
+=============================
 
-请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： ::
+请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板：
 
-    idf.py -p PORT [-b BAUD] flash
+    ``idf.py -p PORT [-b BAUD] flash``
 
 请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。
 
-您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为  ``460800``。
+您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
 
 更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
 
@@ -409,11 +426,11 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 .. _get-started-build-monitor:
 
 第十步：监视器
-==================
+======================
 
 您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
 
-运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： ::
+运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动：::
 
     $ idf.py -p /dev/ttyUSB0 monitor
     Running idf_monitor in directory [...]/esp/hello_world/build
@@ -440,17 +457,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 
 您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。
 
-如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板选用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
+如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
 
 .. figure:: ../../_static/get-started-garbled-output.png
     :align: center
     :alt: 乱码输出
     :figclass: align-center
 
-此时，请您：
+此时，您可以：
 
 1. 退出监视器。
-2. 打开 :ref:`menuconfig <get-started-configure>`，
+2. 打开 :ref:`menuconfig <get-started-configure>`。
 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。
 4. 然后，请重新 :ref:`编译和烧录 <get-started-flash>` 应用程序。
 
@@ -458,7 +475,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 
     您也可以运行以下命令，一次性执行构建、烧录和监视过程：
 
-        ``idf.py -p PORT flash monitor``
+    ``idf.py -p PORT flash monitor``
 
 此外，
 
@@ -470,21 +487,22 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。
 
 更新 ESP-IDF
-=================
+================
 
 乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 
 
-如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH <add-idf_path-to-profile>`。否则，工具链将无法找到 ESP-IDF。
-
 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
 
+注意，更新完成后，请执行 ``install.sh`` （Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。
+
+一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 :ref:`get-started-set-up-env`。
+
 相关文档
-===========
+=================
 
 .. toctree::
     :maxdepth: 1
 
-    add-idf_path-to-profile
     establish-serial-connection
     eclipse-setup
     ../api-guides/tools/idf-monitor

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

@@ -4,7 +4,7 @@
 
 :link_to_translation:`en:[English]`
 
-除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
+除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
 
 安装准备
 =====================
@@ -23,39 +23,38 @@
 
     sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
 
-
 .. note::
     使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
 
 从源代码编译工具链
 =================================
 
-- 安装依赖：
+安装依赖项：
 
-  - CentOS 7::
+- CentOS 7::
 
-        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
+    sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
 
-  - Ubuntu pre-16.04::
+- Ubuntu pre-16.04::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
+    sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
 
-  - Ubuntu 16.04 及以上::
+- Ubuntu 16.04 或以上 ::
 
-        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+    sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
 
-  - Debian 9::
+- Debian 9::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+    sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
 
-  - Arch::
+- Arch::
 
-        TODO
+    TODO
 
 创建工作目录，并进入该目录::
 
-  mkdir -p ~/esp
-  cd ~/esp
+    mkdir -p ~/esp
+    cd ~/esp
 
 下载并编译 ``crosstool-NG`` ：
 
@@ -67,7 +66,7 @@
     ./ct-ng build
     chmod -R u+w builds/xtensa-esp32-elf
 
-编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path>` 的介绍，将工具链添加到 ``PATH``。
+编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path-legacy>` 的介绍，将工具链添加到 ``PATH``。
 
 
 后续步骤

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

@@ -1,10 +1,10 @@
-*******************************************************************
+*********************************************
 Linux 平台工具链的标准设置
-*******************************************************************
+*********************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
-安装前提
+安装准备
 =====================
 
 编译 ESP-IDF 需要以下软件包：
@@ -15,94 +15,41 @@ Linux 平台工具链的标准设置
 
 - Ubuntu 和 Debian::
 
-    sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
 
 .. note::
     使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
 
-工具链的设置
-=========================
-
-.. include:: /_build/inc/download-links.inc
-
-Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
-
-- 64 位 Linux：
-
-  |download_link_linux64|
-
-- 32 位 Linux：
-
-  |download_link_linux32|
-
-1.  下载完成后，将它解压到 ``~/esp`` 目录：
-
-    - for 64-bit Linux:
-
-      .. include:: /_build/inc/unpack-code-linux64.inc
-
-    - for 32-bit Linux:
-
-      .. include:: /_build/inc/unpack-code-linux32.inc
-
-.. _setup-linux-toolchain-add-it-to-path:
-
-2.  工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
-
-    要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：::
-
-      export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
-
-    或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可::
-
-      alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
-
-    然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
-
-    .. note::
-
-        如果将 ``/bin/bash`` 设置为登录 shell，且同时存在  ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。
-
-3.  退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
-
-        printenv PATH
-
-    检查字符串的开头是否包含类似的工具链路径::
-
-        $ printenv PATH
-        /home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
-
-     除了 ``/home/user-name``，应该有具体的安装的主路径。
-
+其他提示
+===============
 
 权限问题 /dev/ttyUSB0
-----------------------------------------------
+------------------------------------------------------------
+
+使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`。
 
-使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`
+ncurses 5 依赖项
+--------------------
 
-Arch Linux 用户
---------------------------------
+在 Linux 上运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但一些较新版本默认只提供 ncurses 6。
 
-在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
+请查看对应版本信息，确认是否存在可用的 ncurses 5。此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
 
-`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
+Arch Linux 用户可在 AUR_ 中获得 native 和 lib32 配置的 ncurses 5 库：
 
 - https://aur.archlinux.org/packages/ncurses5-compat-libs/
 - https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
 
-在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。
-
-或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
-
+在安装这些软件包之前，您可能需要将作者的公钥添加到您的密钥环中，具体参考上方的“注释”部分。
 
 后续步骤
-================
+==========
 
-后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
 
 
 相关文档
@@ -115,3 +62,4 @@ Arch Linux 用户
 
 
 .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
+

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

@@ -1,86 +1,87 @@
-*********************************************************************
-从零开始设置 Mac OS 环境下的工具链
-*********************************************************************
+***********************************************
+从零开始设置 MacOS 环境下的工具链
+***********************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
 软件包管理器
-======================
+===============
 
-从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
+从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
 
-MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。
+MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。
 
-    .. _homebrew: https://brew.sh/
-    .. _MacPorts: https://www.macports.org/install.php
+.. _homebrew: https://brew.sh/
+.. _MacPorts: https://www.macports.org/install.php
 
-请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看在哪些情景下需要从头开始设置工具链。
+请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看可能需要从头开始设置工具链的情况。
 
-准备工作
-============================
+安装准备
+=====================
 
 - 安装 pip::
 
-    sudo easy_install pip
+	sudo easy_install pip
 
 - 安装 pyserial::
 
-    pip install --user pyserial
+	pip install --user pyserial
 
 - 安装 CMake 和 Ninja 编译工具：
 
-  - 若使用 HomeBrew，你可以运行::
+	- 若有 HomeBrew，您可以运行::
 
-      brew install cmake ninja
+		brew install cmake ninja
 
-  - 若使用 MacPorts，你可以运行::
+	- 若有 MacPorts，您可以运行::
 
-      sudo port install cmake ninja
+		sudo port install cmake ninja
 
 从源代码编译工具链
-========================================
+=================================
 
-- 相关安装：
+安装依赖项：
 
-  - 对于 MacPorts::
+- 对于 MacPorts::
 
-        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
+	sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
 
-  - 对于 homebrew::
+- 对于 homebrew::
 
-        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
+	brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
 
 创建一个文件系统镜像（区分大小写）::
 
-    hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
+	hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
 
 挂载::
 
-    hdiutil mount ~/esp/crosstool.dmg
+	hdiutil mount ~/esp/crosstool.dmg
 
-创建指向你工作目录的符号链接::
+创建指向您工作目录的符号链接::
 
-    mkdir -p ~/esp
-    ln -s /Volumes/ctng ~/esp/ctng-volume
+	mkdir -p ~/esp
+	ln -s /Volumes/ctng ~/esp/ctng-volume
 
-前往新创建的目录：::
+前往新创建的目录 ::
 
-    cd ~/esp/ctng-volume
+	cd ~/esp/ctng-volume
 
-下载 ``crosstool-NG``，并开始编译：
+下载并编译 ``crosstool-NG`` 
 
 .. include:: /_build/inc/scratch-build-code.inc
 
-编译工具链：::
+编译工具链::
 
-    ./ct-ng xtensa-esp32-elf
-    ./ct-ng build
-    chmod -R u+w builds/xtensa-esp32-elf
+	./ct-ng xtensa-esp32-elf
+	./ct-ng build
+	chmod -R u+w builds/xtensa-esp32-elf
 
-编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
+编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。
 
 
 后续步骤
-=================
+==========
+
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
 
-继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。

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

@@ -1,8 +1,8 @@
-******************************************************************
-在 Mac OS 上安装 ESP32 工具链
-******************************************************************
+**********************************************
+MacOS 平台工具链的标准设置
+**********************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
 安装准备
 =====================
@@ -19,64 +19,30 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
 
 - 安装 CMake 和 Ninja 编译工具：
 
-  - 若有 HomeBrew_，你可以运行::
+    - 若有 HomeBrew_，您可以运行::
 
-      brew install cmake ninja
+        brew install cmake ninja
 
-  - 若有 MacPorts_，你可以运行::
+    - 若有 MacPorts_，您可以运行::
 
-      sudo port install cmake ninja
+        sudo port install cmake ninja
 
-  - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 
+    - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
 
-- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
+- 强烈建议同时安装 ccache_ 以获得更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
 
 .. note::
+    
+    如您在上述任何步骤中遇到以下错误::
 
-   如在任一步骤中出现以下报错信息::
-
-   ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun``
-
-   你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。
-
-安装工具链
-======================
-
-.. include:: /_build/inc/download-links.inc
-
-下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网：
-
-|download_link_osx|
-
-完成下载后，请在 ``~/esp`` 目录下进行解压：
-
-.. include:: /_build/inc/unpack-code-osx.inc
-
-.. _setup-macos-toolchain-add-it-to-path:
-
-此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。
-
-为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：::
-
-    export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
-
-此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令::
-
-    alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
-
-此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。
-
-注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。
-
-此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确::
-
-        printenv PATH
+    ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at:/Library/Developer/CommandLineTools/usr/bin/xcrun``
 
+    则必须安装 XCode 命令行工具，具体可运行 ``xcode-select --install``。
 
 后续步骤
-=================
+==========
 
-前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
 
 相关文档
 =================
@@ -91,3 +57,4 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
 .. _ccache: https://ccache.samba.org/
 .. _homebrew: https://brew.sh/
 .. _MacPorts: https://www.macports.org/install.php
+

docs/zh_CN/get-started/toolchain-setup-scratch.rst

@@ -1,17 +1,17 @@
 .. _get-started-customized-setup:
 
-*********************************************************
-工具链自定义设置
-*********************************************************
+*************************************
+工具链的自定义设置
+*************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
-除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。
+除了从乐鑫官网（请见 :ref:`get-started-set-up-tools`）下载二进制工具链外，您还可以自行编译工具链。
 
-如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链：
+如无特殊需求，建议直接使用我们提供的预编译二进制工具链。不过，您可以在以下情况考虑自行编译工具链：
 
 - 需要定制工具链编译配置
-- 使用其他 GCC 版本（如 4.8.5）
+- 需要使用其他 GCC 版本（如 4.8.5）
 - 需要破解 gcc、newlib 或 libstdc++
 - 有相关兴趣或时间充裕
 - 不信任从网站下载的 bin 文件
@@ -19,9 +19,10 @@
 如需自行编译工具链，请查看以下文档：
 
 .. toctree::
-    :maxdepth: 1
+	:maxdepth: 1
+
+	windows-setup-scratch
+	linux-setup-scratch
+	macos-setup-scratch
 
-    windows-setup-scratch
-    linux-setup-scratch
-    macos-setup-scratch
 

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

@@ -1,72 +1,99 @@
-******************************************************************
+********************************************
 从零开始设置 Windows 环境下的工具链
-******************************************************************
+********************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
-本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 <windows-setup>` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。
+除了使用 :doc:`ESP-IDF 工具安装器 <windows-setup>`，用户也可以手动设置 Windows 环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。
 
 使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。
 
+.. note::
+    基于 GNU Make 的构建系统要求 Windows 兼容 MSYS2_ Unix，基于 CMake 的构建系统则无此要求。
+
+.. _get-esp-idf-windows-command-line:
+
+获取 ESP-IDF
+=================
 
 .. note::
-   基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。
+
+    较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
+
+    请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
+
+打开命令提示符，运行以下命令：
+
+.. include:: /_build/inc/git-clone-windows.inc
+
+ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
+
+请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
+
+.. include:: /_build/inc/git-clone-notes.inc
+
+.. note::
+
+    在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 ::
+    
+        cd esp-idf
+        git submodule update --init
+
 
 工具
 =====
 
-cmake
-^^^^^
+cmake 工具
+^^^^^^^^^^
 
 下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。
 
-当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
+当安装器询问“安装选项”时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
 
 Ninja 编译工具
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. note::
-    Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。
+    目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。
 
-从（`下载页面 <ninja-dl>`_）下载最新发布的 Windows 平台稳定版 `ninja`_。 
+从（`下载页面 <ninja-dl_>`_）下载最新发布的 Windows 平台稳定版 ninja_。 
 
-适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 <add-directory-windows-path>`_ （或者选择你的路径中已有的目录）。
+适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>` （或者选择您路径中的已有目录）。
 
 
 Python 2.x
 ^^^^^^^^^^
 
-下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。 
+下载并运行适用于 Windows 安装器的最新版 Python_ 2.7。
 
-Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。
+Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到路径中）。请将该选项更改到 "Will be installed"（将会安装）。
 
-Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令::
+Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”窗口，并运行以下命令::
 
-  pip install --user pyserial
+    pip install --user pyserial
 
 适用于 IDF 的 MConf
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-从 `kconfig-frontends 发布页面 <mconf-idf>`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。
+从 `kconfig-frontends releases page`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。
 
-你需将此工具解压到目录，然后 `添加到你的路径 <add-directory-windows-path>`_。
+请将此工具解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>`。
 
 工具链设置
 ===============
 
 .. include:: /_build/inc/download-links.inc
 
-下载预编译的 Windows 平台工具链：
+下载预编译的 Windows 工具链：
 
 |download_link_win32|
 
-解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。
+解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。
 
-然后，须将该目录下的子目录 ``bin`` `添加到你的路径 <add-directory-windows-path>`_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
+然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 <add-directory-windows-path>`。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
 
 .. note::
-
-   如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
+    如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
 
 
 .. _add-directory-windows-path:
@@ -74,19 +101,24 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并
 添加目录到路径
 ========================
 
-添加任何新目录到你的 Windows Path 环境变量：
+在 Windows 环境下，向 Path 环境变量增加任何新目录，请：
 
-打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。
+打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。
 
-双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
+双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
 
 
 后续步骤
-================
+==========
 
-要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
+继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
 
+.. _cmake: https://cmake.org/download/
 .. _ninja: https://ninja-build.org/
+.. _ninja-dl: https://github.com/ninja-build/ninja/releases
 .. _Python: https://www.python.org/downloads/windows/
 .. _MSYS2: https://msys2.github.io/
+.. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases
+.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
+
 

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

@@ -1,3 +1,41 @@
-:orphan:
+*************************************************
+在 Windows 环境下更新 ESP-IDF 工具
+*************************************************
+
+.. _get-started-install_bat-windows:
+
+使用脚本安装 ESP-IDF 工具
+====================================
+
+请从 Windows “命令提示符”窗口，切换至 ESP-IDF 的安装目录。然后运行::
+
+	install.bat
+
+对于 Powershell，请切换至 ESP-IDF 的安装目录。然后运行::
+
+	install.ps1
+
+该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。
+该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。
+
+.. _get-started-export_bat-windows:
+
+使用“导出脚本”将 ESP-IDF 工具添加至 PATH
+=================================================================================
+
+ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。
+
+有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。
+
+首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``::
+
+	cd %userprofile%\esp\esp-idf
+	export.bat
+
+对于 Powershell 用户，请同样切换至 ESP-IDF 的安装路径，然后执行 ``export.ps1``::
+
+	cd ~/esp/esp-idf
+	export.ps1
+
+运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。
 
-.. Remove this file when the Chinese translation of getting started guide is updated

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

@@ -1,54 +1,52 @@
-**********************************************************
+***********************************************
 Windows 平台工具链的标准设置
-**********************************************************
+***********************************************
 
-:link_to_translation:`en:[英文]`
+:link_to_translation:`en:[English]`
 
 .. note::
-      基于 CMake 的构建系统仅支持 64 位版本 Windows。
+	目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。
 
-引言
+概述
 ============
 
-ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。
+ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和  Ninja 编译工具等。
 
-在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse <eclipse-setup>` 或支持 CMake 的图形化工具 IDE。
+在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse <eclipse-setup>` 或其他支持 CMake 的图形化工具 IDE。
 
-https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
+.. note::
+	较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。
+
+.. _get-started-windows-tools-installer:
 
 ESP-IDF 工具安装器
 =======================
 
-安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
-
-https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
+要安装 ESP-IDF 必备工具，最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
 
-安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。
+https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
 
-安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。 
+本安装器可为您安装所需的交叉编译器、OpenOCD、cmake_ 和 Ninja_ 编译工具，以及一款 mconf-idf_ 配置工具。此外，本安装器还可在有需要时下载、运行 Python_ 3.7 和 `Git For Windows` 的安装器。
 
-请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。
+本安装器还可用于下载任意 ESP-IDF 发布版本。
 
-安装 Git
-==============
+使用命令提示符
+========================
 
-ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。
+在后续步骤中，我们将使用 Windows 的命令提示符进行操作。
 
-如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。
+ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 命令提示符窗口的快捷方式。本快捷方式可以打开 Windows 命令提示符（即 cmd.exe），并运行 ``export.bat`` 脚本以设置各环境变量（比如 ``PATH``，``IDF_PATH`` 等）。此外，您可还以通过 Windows 命令提示符使用各种已经安装的工具。
 
-使用终端
-================
+注意，本快捷方式仅适用 ESP-IDF 工具安装器中指定的 ESP-IDF 路径。如果您的电脑上存在多个 ESP-IDF（比如您需要不同的 ESP-IDF 版本）需要使用快捷方式，您可以：
 
-在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符：
+1. 为 ESP-IDF 工具安装器创建的快捷方式创建一个副本，并将新快捷方式的“当前路径”指定为您希望使用的 ESP-IDF 路径。
 
-- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。
-- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。
-- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。
+2. 运行 ``cmd.exe``，并更新至您希望使用的 ESP-IDF 目录，然后运行 ``export.bat``。注意，这种方法要求 ``PATH`` 中存在 Python 和 Git。如果您在使用时遇到有关“找不到 Python 或 Git” 的错误信息，请使用第一种方法。
 
 后续步骤
 ==========
 
-要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
+当 ESP-IDF 工具安装器安装完成后，则开发环境设置也到此结束。后续开发步骤，请前往 :ref:`get-started-start-project` 查看。
 
 相关文档
 =================
@@ -59,7 +57,7 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你
     :maxdepth: 1
 
     windows-setup-scratch
-
+    windows-setup-update
 
 .. _MSYS2: https://msys2.github.io/
 .. _cmake: https://cmake.org/download/
@@ -68,3 +66,4 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你
 .. _Git for Windows: https://gitforwindows.org/
 .. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
 .. _Github Desktop: https://desktop.github.com/
+