Docs: Update folder structure for 5.1 migration

docs/conf_common.py

@@ -33,7 +33,7 @@ BT_DOCS = ['api-guides/blufi.rst',
            'api-reference/bluetooth/esp_blufi.rst',
            'api-reference/bluetooth/index.rst',
            'api-reference/bluetooth/nimble/index.rst',
-           'migration-guides/release-5.x/bluetooth-low-energy.rst']
+           'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
 
 BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst',
@@ -53,7 +53,7 @@ CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_hf_ag.rst',
                    'api-reference/bluetooth/esp_spp.rst',
                    'api-reference/bluetooth/esp_gap_bt.rst',
-                   'migration-guides/release-5.x/bluetooth-classic.rst']
+                   'migration-guides/release-5.x/5.0/bluetooth-classic.rst']
 
 WIFI_DOCS = ['api-guides/wifi.rst',
              'api-guides/wifi-security.rst',

docs/en/migration-guides/index.rst

@@ -9,4 +9,5 @@ ESP-IDF 5.x Migration Guide
 .. toctree::
     :maxdepth: 1
 
-    release-5.x/index
+    release-5.x/5.0/index
+    release-5.x/5.1/index

docs/en/migration-guides/release-5.x/index.rst → docs/en/migration-guides/release-5.x/5.0/index.rst

@@ -18,13 +18,3 @@ Migration from 4.4 to 5.0
     storage
     system
     tools
-
-.. Please create a separate file for each minor release, for example:
-
-.. Migration from 5.0 to 5.1
-.. -------------------------
-
-.. toctree::
-..    :maxdepth: 1
-
-..    release-5.1

docs/en/migration-guides/release-5.x/networking.rst → docs/en/migration-guides/release-5.x/5.0/networking.rst

@@ -61,7 +61,7 @@ SPI-Ethernet Module Initialization
 
 The SPI-Ethernet Module initialization is now simplified. Previously, you had to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
 
-Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide<../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
+Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide<../../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
 
 
 .. _tcpip-adapter:

docs/en/migration-guides/release-5.x/peripherals.rst → docs/en/migration-guides/release-5.x/5.0/peripherals.rst

@@ -87,7 +87,7 @@ GPIO
     Sigma-Delta Modulator
     ---------------------
 
-    The Sigma-Delta Modulator driver has been redesigned into :doc:`SDM <../../api-reference/peripherals/sdm>`.
+    The Sigma-Delta Modulator driver has been redesigned into :doc:`SDM <../../../api-reference/peripherals/sdm>`.
 
     - The new driver implements a factory pattern, where the SDM channels are managed in a pool internally, thus users don't have to fix a SDM channel to a GPIO manually.
     - All SDM channels can be allocated dynamically.
@@ -117,7 +117,7 @@ GPIO
 Timer Group Driver
 ------------------
 
-Timer Group driver has been redesigned into :doc:`GPTimer <../../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer.
+Timer Group driver has been redesigned into :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer.
 
 Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will trigger the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
 
@@ -240,7 +240,7 @@ LEDC
     Pulse Counter Driver
     --------------------
 
-    Pulse counter driver has been redesigned (see :doc:`PCNT <../../api-reference/peripherals/pcnt>`), which aims to unify and simplify the usage of PCNT peripheral.
+    Pulse counter driver has been redesigned (see :doc:`PCNT <../../../api-reference/peripherals/pcnt>`), which aims to unify and simplify the usage of PCNT peripheral.
 
     Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/pcnt.h``. However, including ``driver/pcnt.h`` will trigger the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN`.
 
@@ -294,14 +294,14 @@ LEDC
 
     Configuration contents has been changed. In the old version, users need to configure ``clk_div`` and ``dac_offset``. While in the new version, users only need to choose ``tsens_range``.
 
-    The process of using temperature sensor has been changed. In the old version, users can use ``config->start->read_celsius`` to get value. In the new version, users should install the temperature sensor driver firstly, by ``temperature_sensor_install`` and uninstall it when finished. For more information, please refer to :doc:`Temperature Sensor <../../api-reference/peripherals/temp_sensor>` .
+    The process of using temperature sensor has been changed. In the old version, users can use ``config->start->read_celsius`` to get value. In the new version, users should install the temperature sensor driver firstly, by ``temperature_sensor_install`` and uninstall it when finished. For more information, please refer to :doc:`Temperature Sensor <../../../api-reference/peripherals/temp_sensor>` .
 
 .. only:: SOC_RMT_SUPPORTED
 
     RMT Driver
     ----------
 
-    RMT driver has been redesigned (see :doc:`RMT transceiver <../../api-reference/peripherals/rmt>`), which aims to unify and extend the usage of RMT peripheral.
+    RMT driver has been redesigned (see :doc:`RMT transceiver <../../../api-reference/peripherals/rmt>`), which aims to unify and extend the usage of RMT peripheral.
 
     Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/rmt.h``. However, including ``driver/rmt.h`` will trigger the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN`.
 
@@ -376,7 +376,7 @@ LCD
     MCPWM
     -----
 
-    MCPWM driver was redesigned (see :doc:`MCPWM <../../api-reference/peripherals/mcpwm>`), meanwhile, the legacy driver is deprecated.
+    MCPWM driver was redesigned (see :doc:`MCPWM <../../../api-reference/peripherals/mcpwm>`), meanwhile, the legacy driver is deprecated.
 
     The new driver's aim is to make each MCPWM submodule independent to each other, and give the freedom of resource connection back to users.
 
@@ -454,13 +454,13 @@ LCD
     I2S driver
     ----------
 
-    The I2S driver has been redesigned (see :doc:`I2S Driver <../../api-reference/peripherals/i2s>`), which aims to rectify the shortcomings of the driver that were exposed when supporting all the new features of ESP32-C3 & ESP32-S3. The new driver's APIs are available by including corresponding I2S mode's header files :component_file:`driver/include/driver/i2s_std.h`, :component_file:`driver/include/driver/i2s_pdm.h`, or :component_file:`driver/include/driver/i2s_tdm.h`.
+    The I2S driver has been redesigned (see :doc:`I2S Driver <../../../api-reference/peripherals/i2s>`), which aims to rectify the shortcomings of the driver that were exposed when supporting all the new features of ESP32-C3 & ESP32-S3. The new driver's APIs are available by including corresponding I2S mode's header files :component_file:`driver/include/driver/i2s_std.h`, :component_file:`driver/include/driver/i2s_pdm.h`, or :component_file:`driver/include/driver/i2s_tdm.h`.
 
     Meanwhile, the old driver's APIs in :component_file:`driver/deprecated/driver/i2s.h` are still supported for backward compatibility. But there will be warnings if users keep using the old APIs in their projects, these warnings can be suppressed by the Kconfig option :ref:`CONFIG_I2S_SUPPRESS_DEPRECATE_WARN`.
 
     Here is the general overview of the current I2S files:
 
-    .. figure:: ../../../_static/diagrams/i2s/i2s_file_structure.png
+    .. figure:: ../../../../_static/diagrams/i2s/i2s_file_structure.png
         :align: center
         :alt: I2S File Structure
 

docs/en/migration-guides/release-5.x/removed-components.rst → docs/en/migration-guides/release-5.x/5.0/removed-components.rst

@@ -47,7 +47,7 @@ The following components are removed since they were deprecated in IDF v4.x:
     OpenSSL-API component is no longer supported. It is not available in the IDF Component Registry, either. Please use :doc:`ESP-TLS </api-reference/protocols/esp_tls>` or :component:`mbedtls` API directly.
 
 .. note::
-    ``esp_adc_cal`` component is no longer supported. New adc calibration driver is in ``esp_adc`` component. Legacy adc calibration driver has been moved into ``esp_adc`` component. To use legacy ``esp_adc_cal`` driver APIs, you should add ``esp_adc`` component to the list of component requirements in CMakeLists.txt. Also check :doc:`Peripherals Migration Guide </migration-guides/release-5.x/peripherals>` for more details.
+    ``esp_adc_cal`` component is no longer supported. New adc calibration driver is in ``esp_adc`` component. Legacy adc calibration driver has been moved into ``esp_adc`` component. To use legacy ``esp_adc_cal`` driver APIs, you should add ``esp_adc`` component to the list of component requirements in CMakeLists.txt. Also check :doc:`Peripherals Migration Guide </migration-guides/release-5.x/5.0/peripherals>` for more details.
 
 The targets components are no longer necessary after refactoring and have been removed:
 

docs/en/migration-guides/release-5.x/system.rst → docs/en/migration-guides/release-5.x/5.0/system.rst

@@ -90,7 +90,7 @@ SOC Dependency
 APP Trace
 ---------
 
-One of the timestamp sources has changed from the legacy timer group driver to the new :doc:`GPTimer <../../api-reference/peripherals/gptimer>`. Kconfig choices like ``APPTRACE_SV_TS_SOURCE_TIMER00`` has been changed to ``APPTRACE_SV_TS_SOURCE_GPTIMER``. User no longer need to choose the group and timer ID.
+One of the timestamp sources has changed from the legacy timer group driver to the new :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`. Kconfig choices like ``APPTRACE_SV_TS_SOURCE_TIMER00`` has been changed to ``APPTRACE_SV_TS_SOURCE_GPTIMER``. User no longer need to choose the group and timer ID.
 
 esp_timer
 -----------

docs/en/migration-guides/release-5.x/5.1/index.rst

@@ -0,0 +1,9 @@
+Migration from 5.0 to 5.1
+-------------------------
+
+:link_to_translation:`zh_CN:[中文]`
+
+.. toctree::
+    :maxdepth: 1
+
+    peripherals

docs/en/migration-guides/release-5.x/5.1/peripherals.rst

@@ -0,0 +1,5 @@
+Peripherals
+===========
+
+:link_to_translation:`zh_CN:[中文]`
+

docs/zh_CN/migration-guides/index.rst

@@ -9,4 +9,5 @@
 .. toctree::
     :maxdepth: 1
 
-    release-5.x/index
+    release-5.x/5.0/index
+    release-5.x/5.1/index

docs/zh_CN/migration-guides/release-5.x/index.rst → docs/zh_CN/migration-guides/release-5.x/5.0/index.rst

@@ -18,13 +18,3 @@
     storage
     system
     tools
-
-.. Please create a separate file for each minor release, for example:
-
-.. 从 5.0 迁移到 5.1
-.. -----------------
-
-.. toctree::
-..    :maxdepth: 1
-
-..    release-5.1

docs/zh_CN/migration-guides/release-5.x/networking.rst → docs/zh_CN/migration-guides/release-5.x/5.0/networking.rst

@@ -61,7 +61,7 @@ SPI 以太网模块初始化
 
 SPI 以太网模块的初始化过程已经简化。此前，您需要在实例化 SPI 以太网 MAC 之前，使用 :cpp:func:`spi_bus_add_device` 手动分配 SPI 设备。
 
-现在，由于 SPI 设备已在内部分配，您无需再调用 :cpp:func:`spi_bus_add_device`。:cpp:class:`eth_dm9051_config_t`、:cpp:class:`eth_w5500_config_t` 和 :cpp:class:`eth_ksz8851snl_config_t` 配置结构体现已包含 SPI 设备配置成员（例如，可以微调可能依赖 PCB 设计的 SPI 时序）。``ETH_DM9051_DEFAULT_CONFIG``、``ETH_W5500_DEFAULT_CONFIG`` 和 ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` 配置初始化宏也已接受新的参数输入。了解 SPI 以太网模块初始化示例，请查看 :doc:`以太网 API 参考指南<../../api-reference/network/esp_eth>`。
+现在，由于 SPI 设备已在内部分配，您无需再调用 :cpp:func:`spi_bus_add_device`。:cpp:class:`eth_dm9051_config_t`、:cpp:class:`eth_w5500_config_t` 和 :cpp:class:`eth_ksz8851snl_config_t` 配置结构体现已包含 SPI 设备配置成员（例如，可以微调可能依赖 PCB 设计的 SPI 时序）。``ETH_DM9051_DEFAULT_CONFIG``、``ETH_W5500_DEFAULT_CONFIG`` 和 ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` 配置初始化宏也已接受新的参数输入。了解 SPI 以太网模块初始化示例，请查看 :doc:`以太网 API 参考指南<../../../api-reference/network/esp_eth>`。
 
 
 .. _tcpip-adapter:

docs/zh_CN/migration-guides/release-5.x/peripherals.rst → docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst

@@ -87,7 +87,7 @@ GPIO
     Sigma-Delta 调制器
     ---------------------------------
 
-    Sigma-Delta 调制器的驱动现已更新为 :doc:`SDM <../../api-reference/peripherals/sdm>`。
+    Sigma-Delta 调制器的驱动现已更新为 :doc:`SDM <../../../api-reference/peripherals/sdm>`。
     
     - 新驱动中实现了工厂模式，SDM 通道都位于内部通道池中，因此用户无需手动将 SDM 通道配置到 GPIO 管脚。
     - SDM 通道会被自动分配。
@@ -117,7 +117,7 @@ GPIO
 定时器组驱动
 -----------------------------------------
 
-为统一和简化通用定时器的使用，定时器组驱动已更新为 :doc:`GPTimer <../../api-reference/peripherals/gptimer>`。
+为统一和简化通用定时器的使用，定时器组驱动已更新为 :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`。
 
 尽管我们推荐使用新的驱动 API， 旧版驱动仍然可用，其头文件引用路径为 ``driver/timer.h``。但是，引用 ``driver/timer.h`` 会默认触发如下编译警告，可通过配置 Kconfig 选项 :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN` 关闭该警告。
 
@@ -240,7 +240,7 @@ LEDC
     脉冲计数器 (PCNT) 驱动
     ----------------------------------
     
-    为统一和简化 PCNT 外设，PCNT 驱动已更新，详见 :doc:`PCNT <../../api-reference/peripherals/pcnt>`。
+    为统一和简化 PCNT 外设，PCNT 驱动已更新，详见 :doc:`PCNT <../../../api-reference/peripherals/pcnt>`。
     
     尽管我们推荐使用新的驱动 API，旧版驱动仍然可用，保留在头文件引用路径 ``driver/pcnt.h`` 中。但是，引用路径 ``driver/pcnt.h`` 会默认触发如下编译警告，可通过配置 Kconfig 选项 :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN` 来关闭该警告。
 
@@ -294,14 +294,14 @@ LEDC
 
     配置内容已更新。更新前，用户需要设置 ``clk_div`` 与 ``dac_offset``。更新后，用户仅需设置 ``tsens_range``。
 
-    温度传感器的使用过程也已更新。更新前，用户可通过 ``config->start->read_celsius`` 获取数据。更新后，用户需要通过 ``temperature_sensor_install`` 先安装温度传感器的驱动，测量完成后需卸载驱动，详情请参考 :doc:`Temperature Sensor <../../api-reference/peripherals/temp_sensor>`。
+    温度传感器的使用过程也已更新。更新前，用户可通过 ``config->start->read_celsius`` 获取数据。更新后，用户需要通过 ``temperature_sensor_install`` 先安装温度传感器的驱动，测量完成后需卸载驱动，详情请参考 :doc:`Temperature Sensor <../../../api-reference/peripherals/temp_sensor>`。
 
 .. only:: SOC_RMT_SUPPORTED
 
     RMT 驱动
     ----------------------
 
-    为统一和扩展 RMT 外设的使用，RMT 驱动已更新，详见 :doc:`RMT transceiver <../../api-reference/peripherals/rmt>`。
+    为统一和扩展 RMT 外设的使用，RMT 驱动已更新，详见 :doc:`RMT transceiver <../../../api-reference/peripherals/rmt>`。
     
     尽管我们建议使用新的驱动 API，旧版驱动仍然可用，保留在头文件引用路径 ``driver/rmt.h``中。但是，引用路径 ``driver/rmt.h`` 会默认触发如下编译警告，可通过配置 Kconfig 选项 :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN` 来关闭该警告。
     
@@ -376,7 +376,7 @@ LCD
     MCPWM
     -----
 
-    MCPWM 驱动已更新（详见 :doc:`MCPWM <../../api-reference/peripherals/mcpwm>`）。同时，旧版驱动已被弃用。
+    MCPWM 驱动已更新（详见 :doc:`MCPWM <../../../api-reference/peripherals/mcpwm>`）。同时，旧版驱动已被弃用。
     
     新驱动中，每个 MCPWM 子模块相互独立，用户可以自由进行资源连接。
     
@@ -454,13 +454,13 @@ LCD
     I2S 驱动
     -----------------------
 
-    旧版 I2S 驱动在支持 ESP32-C3 和 ESP32-S3 新功能时暴露了很多缺点，为解决这些缺点，I2S 驱动已更新（请参考:doc:`I2S Driver <../../api-reference/peripherals/i2s>`）。用户可以通过引用不同 I2S 模式对应的头文件来使用新版驱动的 API，如 :component_file:`driver/include/driver/i2s_std.h`， :component_file:`driver/include/driver/i2s_pdm.h` 以及 :component_file:`driver/include/driver/i2s_tdm.h`。 
+    旧版 I2S 驱动在支持 ESP32-C3 和 ESP32-S3 新功能时暴露了很多缺点，为解决这些缺点，I2S 驱动已更新（请参考:doc:`I2S Driver <../../../api-reference/peripherals/i2s>`）。用户可以通过引用不同 I2S 模式对应的头文件来使用新版驱动的 API，如 :component_file:`driver/include/driver/i2s_std.h`， :component_file:`driver/include/driver/i2s_pdm.h` 以及 :component_file:`driver/include/driver/i2s_tdm.h`。 
     
     为保证前向兼容，旧版驱动的 API 仍然在 :component_file:`driver/deprecated/driver/i2s.h` 中可用。但使用旧版 API 会触发编译警告，该警告可通过配置 Kconfig 选项 :ref:`CONFIG_I2S_SUPPRESS_DEPRECATE_WARN` 来关闭。
     
     以下是更新后的 I2S 文件概况。
 
-    .. figure:: ../../../_static/diagrams/i2s/i2s_file_structure.png
+    .. figure:: ../../../../_static/diagrams/i2s/i2s_file_structure.png
         :align: center
         :alt: I2S File Structure
 

docs/zh_CN/migration-guides/release-5.x/removed-components.rst → docs/zh_CN/migration-guides/release-5.x/5.0/removed-components.rst

@@ -46,7 +46,7 @@ IDF v4.x 版本中已不再使用以下组件，这些组件已弃用：
     不再支持 OpenSSL-API 组件。IDF Component Registry 中也没有该组件。请直接使用 :doc:`ESP-TLS </api-reference/protocols/esp_tls>` 或 :component:`mbedtls` API。
 
 .. note::
-    不再支持 esp_adc_cal 组件。 新的 adc 校准驱动在 esp_adc 组件中。旧版 adc 校准驱动已被迁移进 esp_adc 组件中。 要使用旧版 esp_adc_cal 驱动接口，你应该在 CMakeLists.txt 文件的组件依赖列表中增加 esp_adc 。更多细节请查看 :doc:`Peripherals Migration Guide </migration-guides/release-5.x/peripherals>`。
+    不再支持 esp_adc_cal 组件。 新的 adc 校准驱动在 esp_adc 组件中。旧版 adc 校准驱动已被迁移进 esp_adc 组件中。 要使用旧版 esp_adc_cal 驱动接口，你应该在 CMakeLists.txt 文件的组件依赖列表中增加 esp_adc 。更多细节请查看 :doc:`Peripherals Migration Guide </migration-guides/release-5.x/5.0/peripherals>`。
 
 版本更新后无需目标组件，因此以下目标组件也已经从 ESP-IDF 中删除：
 

docs/zh_CN/migration-guides/release-5.x/system.rst → docs/zh_CN/migration-guides/release-5.x/5.0/system.rst

@@ -90,7 +90,7 @@ SOC 依赖性
 应用跟踪
 --------
 
-其中一个时间戳源已从定时器组驱动改为新的 :doc:`GPTimer <../../api-reference/peripherals/gptimer>`。Kconfig 选项已重新命名，例如 ``APPTRACE_SV_TS_SOURCE_TIMER00`` 已更改为 ``APPTRACE_SV_TS_SOURCE_GPTIMER``。用户已无需选择组和定时器 ID。
+其中一个时间戳源已从定时器组驱动改为新的 :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`。Kconfig 选项已重新命名，例如 ``APPTRACE_SV_TS_SOURCE_TIMER00`` 已更改为 ``APPTRACE_SV_TS_SOURCE_GPTIMER``。用户已无需选择组和定时器 ID。
 
 esp_timer
 -----------

docs/zh_CN/migration-guides/release-5.x/5.1/index.rst

@@ -0,0 +1,9 @@
+从 5.0 迁移到 5.1
+-----------------
+
+:link_to_translation:`en:[English]`
+
+.. toctree::
+    :maxdepth: 1
+
+    peripherals

docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst

@@ -0,0 +1,4 @@
+外设
+============
+
+:link_to_translation:`en:[English]`