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

Closes #16077

Author: Honza0297

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
 =================

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'