Merge branch 'docs/update_docs_based_on_the_second_batch_of_customer_feedbacks' into 'master'

docs: update documents based on doc-855, doc-885, doc-889, doc-897

See merge request espressif/esp-idf!12124

components/hal/include/hal/i2s_types.h

@@ -62,8 +62,8 @@ typedef enum {
     // In order to keep compatibility, remain the old definitions and introduce new definitions,
     I2S_COMM_FORMAT_STAND_I2S   = 0X01, /*!< I2S communication I2S Philips standard, data launch at second BCK*/
     I2S_COMM_FORMAT_STAND_MSB   = 0X03, /*!< I2S communication MSB alignment standard, data launch at first BCK*/
-    I2S_COMM_FORMAT_STAND_PCM_SHORT  = 0x04, /*!< PCM Short standard*/
-    I2S_COMM_FORMAT_STAND_PCM_LONG   = 0x0C, /*!< PCM Long standard*/
+    I2S_COMM_FORMAT_STAND_PCM_SHORT  = 0x04, /*!< PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck cycle.*/
+    I2S_COMM_FORMAT_STAND_PCM_LONG   = 0x0C, /*!< PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles.*/
     I2S_COMM_FORMAT_STAND_MAX, /*!< standard max*/
 
     //old definition will be removed in the future.

docs/en/api-guides/partition-tables.rst

@@ -260,7 +260,7 @@ The command-line interface of `parttool.py` has the following structure:
   parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
 
   # Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
-  parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs "spiffs.bin"
+  parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
 
   # Write to partition 'factory' the contents of a file named 'factory.bin'
   parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory "factory.bin"

docs/en/api-reference/bluetooth/esp-ble-mesh.rst

@@ -126,29 +126,29 @@ Configuration Client/Server Models
 Health Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc
 
 
 Generic Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc
 
 
 Sensor Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc
 
 
 Time and Scenes Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc
 
 
 Lighting Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc
 

docs/en/conf.py

@@ -9,14 +9,14 @@
 try:
     from conf_common import *  # noqa: F403,F401
 except ImportError:
-    import sys
     import os
+    import sys
     sys.path.insert(0, os.path.abspath('..'))
     from conf_common import *  # noqa: F403,F401
 
 # General information about the project.
 project = u'ESP-IDF Programming Guide'
-copyright = u'2016 - 2020, Espressif Systems (Shanghai) CO., LTD'
+copyright = u'2016 - 2021, Espressif Systems (Shanghai) Co., Ltd'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

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

@@ -7,24 +7,25 @@ Standard Setup of Toolchain for Linux
 Install Prerequisites
 =====================
 
-To compile with ESP-IDF you need to get the following packages:
+To compile with ESP-IDF you need to get the following packages. The command to run depends on which distribution of Linux you are using:
 
-- CentOS 7::
+- Ubuntu and Debian::
 
-    sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx
+    sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
 
-CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.
+- CentOS 7 & 8::
 
-- Ubuntu and Debian::
+    sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx
 
-    sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
+CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.
 
 - Arch::
 
     sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util libusb
 
 .. note::
-    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
+    - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
+    - If you do not see your Linux distribution in the above list then please check its documentation to find out which command to use for package installation.
 
 Additional Tips
 ===============

docs/zh_CN/api-guides/partition-tables.rst

@@ -253,7 +253,7 @@ Python API
   parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
 
   # 读取类型为 'data'、子类型为 'spiffs' 的分区，保存到 'spiffs.bin' 文件
-  parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs "spiffs.bin"
+  parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
 
   # 将 'factory.bin' 文件中的内容写入到 'factory' 分区
   parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory "factory.bin"

docs/zh_CN/conf.py

@@ -9,14 +9,14 @@
 try:
     from conf_common import *  # noqa: F403,F401
 except ImportError:
-    import sys
     import os
+    import sys
     sys.path.insert(0, os.path.abspath('..'))
     from conf_common import *  # noqa: F403,F401
 
 # General information about the project.
 project = u'ESP-IDF 编程指南'
-copyright = u'2016 - 2020 乐鑫信息科技（上海）股份有限公司'
+copyright = u'2016 - 2021 乐鑫信息科技（上海）股份有限公司'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

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

@@ -7,24 +7,25 @@ Linux 平台工具链的标准设置
 安装准备
 =====================
 
-编译 ESP-IDF 需要以下软件包：
+编译 ESP-IDF 需要以下软件包。请根据使用的系统，选择合适的安装命令，如下所示：
 
-- CentOS 7::
+- Ubuntu 和 Debian::
 
-    sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx
+    sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
 
-目前仍然支持 CentOS 7，但为了更好的用户体验，建议使用 CentOS 8。
+- CentOS 7 & 8::
 
-- Ubuntu 和 Debian::
+    sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx
 
-    sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
+目前仍然支持 CentOS 7，但为了更好的用户体验，建议使用 CentOS 8。
 
 - Arch::
 
     sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util libusb
 
-.. 注解::
-    使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库，或开启 backports 套件库，或安装 "cmake3" 软件包（不是安装 "cmake"）。
+.. note::
+    - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库，或开启 backports 套件库，或安装 "cmake3" 软件包（不是安装 "cmake"）。
+    - 如果上述列表中，并没有您使用的系统，请参考您所用系统的相关文档，查看安装软件包所用的命令。
 
 其他提示
 ===============