Merge branch 'feature/docs_impr_idf_tools' into 'master'

Docs: Improve the Downloadable Tools page with missing information

Closes IDF-4579

See merge request espressif/esp-idf!16860

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

@@ -35,10 +35,13 @@ Tools installation directory
 
 ``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, ``IDF_TOOLS_PATH`` defaults to ``HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
 
-Inside ``IDF_TOOLS_PATH``, the scripts performing tools installation create the following directories:
+Inside ``IDF_TOOLS_PATH``, the scripts performing tools installation create the following directories and files:
 
 - ``dist`` — where the archives of the tools are downloaded.
 - ``tools`` — where the tools are extracted. The tools are extracted into subdirectories: ``tools/TOOL_NAME/VERSION/``. This arrangement allows different versions of tools to be installed side by side.
+- ``idf-env.json`` — user install options (targets, features) are stored in this file. Targets are selected chip targets for which tools are installed and kept up-to-date. Features determine the Python package set which should be installed. These options will be discussed later.
+- ``python_env`` —  not tools related; virtual Python environments are installed in the sub-directories.
+- ``espidf.constraints.*.txt`` — one constraint file for each ESP-IDF release containing Python package version requirements.
 
 GitHub Assets Mirror
 --------------------
@@ -60,7 +63,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
 :idf_file:`tools/idf_tools.py` script bundled with ESP-IDF performs several functions:
 
 * ``install``: Download the tool into ``${IDF_TOOLS_PATH}/dist`` directory, extract it into ``${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION``.
-  
+
   ``install`` command accepts the list of tools to install, in ``TOOL_NAME`` or ``TOOL_NAME@VERSION`` format. If ``all`` is given, all the tools (required and optional ones) are installed. If no argument or ``required`` is given, only the required tools are installed.
 
 * ``download``: Similar to ``install`` but doesn't extract the tools. An optional ``--platform`` argument may be used to download the tools for the specific platform.
@@ -72,7 +75,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
   - ``shell`` produces output suitable for evaluation in the shell. For example,
 
     ::
-  
+
         export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"
 
     on Linux and macOS, and
@@ -80,7 +83,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
     ::
 
         set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%"
-    
+
     on Windows.
 
     .. note::
@@ -94,16 +97,16 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
   - ``key-value`` produces output in `VARIABLE=VALUE` format, suitable for parsing by other scripts::
 
         PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH
-    
-    Note that the script consuming this output has to perform expansion of ``$VAR`` or ``%VAR%`` patterns found in the output. 
+
+    Note that the script consuming this output has to perform expansion of ``$VAR`` or ``%VAR%`` patterns found in the output.
 
 * ``list``: Lists the known versions of the tools, and indicates which ones are installed.
 
 * ``check``: For each tool, checks whether the tool is available in the system path and in ``IDF_TOOLS_PATH``.
 
-* ``install-python-env``: Create Python virtual environment and install the required Python packages.
+* ``install-python-env``: Create a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory and install there the required Python packages. An optional ``--features`` argument allows one to specify a comma-separated list of features. For each feature a requirements file must exist. For example, feature ``XY`` is a valid feature if ``${IDF_PATH}/requirements.XY.txt`` is an existing file with a list of Python packages to be installed. There is one mandatory ``core`` feature ensuring core functionality of ESP-IDF (build, flash, monitor, debug in console). There can be an arbitrary number of optional features. The selected list of features is stored in ``idf-env.json``. The requirement files contain a list of the desired Python packages to be installed and ``espidf.constraints.*.txt`` downloaded from https://dl.espressif.com and stored in ``${IDF_TOOLS_PATH}`` the package version requirements for a given ESP-IDF version.
 
-* ``check-python-dependencies``: Checks if all required Python packages are installed.
+* ``check-python-dependencies``: Checks if all required Python packages are installed. Packages from ``${IDF_PATH}/requirements.*.txt`` files selected by the feature list of ``idf-env.json`` are checked with the package versions specified in the ``espidf.constraints.*.txt`` file. The constraint file will be downloaded from https://dl.espressif.com if this step hasn't been done already in the last day.
 
 .. _idf-tools-install:
 
@@ -115,9 +118,18 @@ Shell-specific user-facing scripts are provided in the root of ESP-IDF repositor
 * ``install.bat`` for Windows Command Prompt
 * ``install.ps1`` for Powershell
 * ``install.sh`` for Bash
+* ``install.fish`` for Fish
 
 Aside from downloading and installing the tools into ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment.
 
+These scripts accept optionally a comma separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally.
+
+Running the scripts without any optional arguments will install tools for all chip targets (by running ``idf_tools.py install --targets=all``) and Python packages for core ESP-IDF functionality (by running ``idf_tools.py install-python-env --features=core``).
+
+Or for example, ``install.sh esp32`` will install tools only for ESP32. See the :ref:`Getting Started Guide <get-started-set-up-tools>` for more examples.
+
+``install.sh --enable-XY`` will enable feature ``XY`` (by running ``idf_tools.py install-python-env --features=core,XY``).
+
 .. _idf-tools-export:
 
 Export scripts
@@ -128,6 +140,7 @@ Since the installed tools are not permanently added into the user or system ``PA
 * ``export.bat`` for Windows Command Prompt
 * ``export.ps1`` for Powershell
 * ``export.sh`` for Bash
+* ``export.fish`` for Fish
 
 .. note::