Merge branch 'doc/update-guide' into 'master'

docs: how to update ESP-IDF env without updating ESP-IDF itself

Closes IDFGH-15431 and DOC-11528

See merge request espressif/esp-idf!39761

Author: dobairoland

docs/en/api-guides/tools/idf-tools.rst

@@ -35,7 +35,7 @@ This file is used by the :idf_file:`tools/idf_tools.py` script when installing t
 Tools Installation Directory
 ----------------------------
 
-The ``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, the default location will be ``HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
+The ``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, the default location will be ``$HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
 
 Inside the ``IDF_TOOLS_PATH`` directory, the tools installation scripts create the following directories and files:
 
@@ -60,6 +60,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
 
 .. note:: The Espressif download server currently does not mirror everything from GitHub, but only files attached as Assets to some releases, as well as source archives for some releases.
 
+.. _idf-tools-py:
 
 ``idf_tools.py`` Script
 -----------------------
@@ -119,7 +120,7 @@ The :idf_file:`tools/idf_tools.py` script bundled with ESP-IDF performs several
 
 * ``check``: For each tool, checks whether the tool is available in the system path and in ``IDF_TOOLS_PATH``.
 
-* ``install-python-env``: Creates a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory or directly in the directory set by the ``IDF_PYTHON_ENV_PATH`` environment variable, and install the required Python packages there.
+* ``install-python-env``: Creates a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory or directly in the directory set by the ``IDF_PYTHON_ENV_PATH`` environment variable, and installs the required Python packages there. If the Python virtual environment already exists, packages inside are updated to their latest versions with respect to the ``espidf.constraints.*.txt`` file.
 
   * An optional ``--features`` argument allows one to specify a comma-separated list of features to be added or removed.
 

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

@@ -277,18 +277,29 @@ Step 5. First Steps on ESP-IDF
 .. include:: linux-macos-start-project.rst
 .. include:: start-project.rst
 
-Tip: Updating ESP-IDF
-======================
+.. _get-started-update-esp-idf:
+
+Updating ESP-IDF and Python Packages in the ESP-IDF Environment
+===============================================================
 
 It is recommended to update ESP-IDF from time to time, as newer versions fix bugs and/or provide new features. Please note that each ESP-IDF major and minor release version has an associated support period, and when one release branch is approaching end of life (EOL), all users are encouraged to upgrade their projects to more recent ESP-IDF releases, to find out more about support periods, see :doc:`ESP-IDF Versions <../versions>`.
 
 The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
 
-Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
+Another solution is to update only what has changed. For specific instructions, please visit :ref:`Updating ESP-IDF <updating-master>` page.
+
+After updating ESP-IDF, execute the install script again (``./install.sh`` in your ``$IDF_PATH``), in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`.
+
+Once all the new tools are installed, enter the ESP-IDF environment using the export script as described in :ref:`get-started-set-up-env`.
 
-After updating ESP-IDF, execute the Install script again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`.
+Updating Python Packages in the ESP-IDF Environment Without Updating ESP-IDF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some features in ESP-IDF are not included directly in the ESP-IDF repository. Instead, they are provided by Python packages such as ``esp-idf-monitor`` or ``esptool``, which are installed in the ESP-IDF environment by the install script. These packages can be updated independently of ESP-IDF. To update them, simply re-run the install script (``./install.sh`` in your ``$IDF_PATH``). If the ESP-IDF environment already exists, the script will update all Python packages in it to the latest versions compatible with the current ESP-IDF version — without updating the ESP-IDF itself.
+
+.. note::
 
-Once the new tools are installed, update the environment using the Export script. See instructions at :ref:`get-started-set-up-env`.
+    If you are an advanced user and want more control over the update process, you can also check :ref:`idf-tools-py` and its ``install-python-env`` command, which is used by the install script and handles the creation or update of the ESP-IDF environment.
 
 Related Documents
 =================

docs/zh_CN/api-guides/tools/idf-tools.rst

@@ -35,7 +35,7 @@
 工具安装目录
 ----------------------------
 
-``IDF_TOOLS_PATH`` 环境变量指定下载及安装工具的位置。若未设置该变量，Linux 和 macOS 系统的默认下载安装位置为 ``HOME/.espressif``，Windows 系统的默认下载安装位置为 ``%USER_PROFILE%\.espressif``。
+``IDF_TOOLS_PATH`` 环境变量指定下载及安装工具的位置。若未设置该变量，Linux 和 macOS 系统的默认下载安装位置为 ``$HOME/.espressif``，Windows 系统的默认下载安装位置为 ``%USER_PROFILE%\.espressif``。
 
 在 ``IDF_TOOLS_PATH`` 目录下，工具安装脚本会创建以下子目录和文件：
 
@@ -60,6 +60,7 @@ GitHub 资源镜像
 
 .. note:: 目前，乐鑫下载服务器不会镜像 GitHub 上的所有内容，只镜像部分发布版本的附件资源文件及源文件。
 
+.. _idf-tools-py:
 
 ``idf_tools.py`` 脚本
 ---------------------------------------
@@ -119,7 +120,7 @@ ESP-IDF 随附的 :idf_file:`tools/idf_tools.py` 脚本具备以下功能：
 
 * ``check``：检查每个工具是否在系统路径和 ``IDF_TOOLS_PATH`` 中可用。
 
-* ``install-python-env``：在 ``${IDF_TOOLS_PATH}/python_env`` 目录或直接在 ``IDF_PYTHON_ENV_PATH`` 环境变量设置的目录中创建 Python 虚拟环境，并在其中安装所需的 Python 软件包。
+* ``install-python-env``：在 ``${IDF_TOOLS_PATH}/python_env`` 目录或直接在 ``IDF_PYTHON_ENV_PATH`` 环境变量设置的目录中创建 Python 虚拟环境，并在其中安装所需的 Python 软件包。若虚拟环境已存在，系统将根据 ``espidf.constraints.*.txt`` 文件中的约束条件，将环境内的软件包更新至最新兼容版本。
 
   * 参数 ``--features`` 为可选项，用于指定要添加或删除的功能列表，功能之间用逗号分隔。
 

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

@@ -277,18 +277,29 @@ ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，
 .. include:: linux-macos-start-project.rst
 .. include:: start-project.rst
 
-建议：更新 ESP-IDF
-======================
+.. _get-started-update-esp-idf:
+
+ESP-IDF 环境更新：升级 ESP-IDF 与 Python 软件包
+===================================================
 
 乐鑫会不时推出新版本的 ESP-IDF，修复 bug 或提供新的功能。请注意，ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持期限满后，版本停止更新维护，用户可将项目升级到最新的 ESP-IDF 版本。更多关于支持期限的信息，请参考 :doc:`ESP-IDF 版本 <../versions>`。
 
 因此，在使用时，也应注意更新本地版本。最简单的方法是：直接删除本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
 
-另一种方法是仅更新变更的部分，具体方式请前往 :ref:`更新 ESP-IDF <updating>` 章节查看。具体更新步骤会根据使用的 ESP-IDF 版本有所不同。
+另一种方法是仅更新变更的部分，具体方式请参阅 :ref:`更新 ESP-IDF <updating>` 章节。
+
+为确保工具版本符合新 ESP-IDF 的要求，在更新 ESP-IDF 版本后，请在 ``$IDF_PATH`` 目录下重新运行 ``./install.sh`` 脚本。详细说明请参阅 :ref:`get-started-set-up-tools`。
+
+所有新工具安装完成后，请参考 :ref:`get-started-set-up-env`，运行导出脚本并进入 ESP-IDF 开发环境。
 
-注意，更新完成后，请再次运行安装脚本，以防新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。
+ESP-IDF 环境更新：只升级 Python 软件包
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ESP-IDF 的部分功能并非直接包含在主代码库中，而是由 ``esp-idf-monitor``、``esptool`` 等 Python 软件包提供。这些软件包由安装脚本自动部署在 ESP-IDF 环境中，无需升级 ESP-IDF 即可更新，只需重新运行安装脚本（在 ``$IDF_PATH`` 目录下执行 ``./install.sh``）。若 ESP-IDF 环境已存在，则该脚本会在保持 ESP-IDF 版本不变的前提下，将所有 Python 软件包更新至与当前 ESP-IDF 版本兼容的最新版本。
+
+.. note::
 
-一旦重新安装好工具，请使用导出脚本更新环境，具体请参考 :ref:`get-started-set-up-env`。
+    高级用户如需更灵活地控制更新流程，可参考 :ref:`idf-tools-py` 工具及 ``install-python-env`` 命令。此命令被安装脚本调用，专门用于创建或更新 ESP-IDF 环境。
 
 相关文档
 =================

tools/idf_tools.py

@@ -3476,7 +3476,12 @@ def main(argv: List[str]) -> None:
             )
 
     install_python_env = subparsers.add_parser(
-        'install-python-env', help=('Create Python virtual environment and install the required Python packages')
+        'install-python-env',
+        help=(
+            'Create a Python virtual environment and install the required Python packages. '
+            'If the virtual environment already exists, update all Python packages to the latest '
+            'versions compatible with the current ESP-IDF version.'
+        ),
     )
     install_python_env.add_argument(
         '--reinstall', help='Discard the previously installed environment', action='store_true'