IEP-1557: Documentation for the ESP-IDF Manager (#1257)

* IEP-1557: Documentation for the ESP-IDF Manager

* version.js added

Author: alirana01

docs/_static/docs_version.js

@@ -0,0 +1,9 @@
+var DOCUMENTATION_VERSIONS = {
+    DEFAULTS: { has_targets: false,
+                supported_targets: [ "esp32" ]
+              },
+    VERSIONS: [
+        { name: "latest" },
+        { name: "release-v4.0.0", pre_release: true }
+    ]
+};

docs/en/installation.rst

@@ -5,6 +5,7 @@ Configuring and installing the Espressif-IDE involves two main steps:
 
 1. :ref:`Downloading and Installing the Espressif-IDE <esp-idf-installation>`
 2. :ref:`Installing the ESP-IDF and related tools within the Espressif-IDE <esp-idf-tools-installation>`
+3. :ref:`Migrating old workspace to new <esp-idf-tools-migration>`
 
 .. note::
    For Eclipse CDT users who prefer installing the ESP-IDF Eclipse Plugin via the `Update site <https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/>`_, please refer to the :ref:`Update Site Installation Guide <marketplaceupdate>`. 
@@ -15,6 +16,11 @@ Espressif-IDE Installation
 
 To begin, navigate to the section corresponding to your operating system below and follow the provided instructions to install the Espressif-IDE.
 
+Please note that the Espressif-IDE requires that 
+you install ESP-IDF via Espressif Installation Manager (EIM) to manage the ESP-IDF versions and tools.
+For detailed documentation on using the Espressif Installation Manager (EIM), 
+please refer to the official guide `here <https://docs.espressif.com/projects/idf-im-ui/en/latest/>`_.
+
 Windows
 ~~~~~~~~
 .. note::
@@ -26,41 +32,68 @@ macOS/Linux
 ~~~~~~~~~~~~
 Download the Espressif-IDE for your respective operating system from the :ref:`download section <downloads>`. After downloading, launch the IDE and proceed to :ref:`install the necessary ESP-IDF and related tools <esp-idf-tools-installation>`. Please ensure that Java, Python, and Git are installed as prerequisites and are available in the system path before launching the IDE.
 
-ESP-IDF and Tools Installation
--------------------------------
+ESP-IDF and Tools Installation (New Workspace)
+----------------------------------------------
 .. _esp-idf-tools-installation:
 
-The Espressif-IDE provides a tool manager to install and manage ESP-IDF and related tools. Please follow the instructions below for installing ESP-IDF in the Espressif-IDE.
+The Espressif-IDE provides a Tool Manager view that allows you to activate available ESP-IDF versions and manage related tools. To install the ESP-IDF and its tools, first download the Espressif Installation Manager (EIM) from the following `link <https://dl.espressif.com/dl/eim/>`_.
+
+
+After downloading and launching EIM, follow the on-screen instructions to install the required ESP-IDF version and associated tools. Once the installation is complete, you can use the ESP-IDF Manager within the IDE to activate the installed ESP-IDF version in the workspace.
+The Espressif-IDE allows you to download and launch the EIM directly from the IDE, making it easier to manage your ESP-IDF versions and tools. If you are coming trying to open the workspace from and older version of Espressif-IDE you will be prompted to convert the older configuration to use with EIM.
+
+Follow these steps inside the Espressif-IDE to install the ESP-IDF and related tools:
 
 1. Go to ``Espressif > ESP-IDF Manager``. The following editor will open:
 
    .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Editor_Screen.png
 
-2. Click on the ``Add ESP-IDF`` button.
-
-   .. image:: ../../media/ToolsManager/ESP-IDF_Configuration_Download_or_Use_ESP-IDF.png
+2. Click on the ``Launch EIM`` or ``Download & Launch EIM`` button if you have not already downloaded and installed EIM.
 
-   From the screen shown above, you can choose an already downloaded ESP-IDF directory or select and download directly from the given dialog. The ``Git`` and ``Python`` tools must be installed, and if they are configured in the system PATH, they will be preloaded in the view. If not, you can browse to the directory and select the proper executables.
+   You will see the progress of download and installation in the console. Once the EIM is launched, you can use it to install the ESP-IDF and related tools.
 
-3. Click on ``Finish``, which will be enabled after all paths and executables are properly configured.
+3. Once you close the EIM your ESP-IDF Manager editor will be updated with the latest information about the ESP-IDF versions and tools available.
 
 .. note::
-    Please note that the python executable is not the one from the virtual environment created from the installation of the ESP-IDF via other means like from CLI. If you are selecting an already installed ESP-IDF directory IDE will automatically pick up the python once you have installed the tools
+    Please note that the EIM will be the only tool going forward to manage the ESP-IDF versions and tools. The previous versions of the Espressif-IDE used to manage tools internally but now the only point of entry into the ESP-IDF will be through the EIM.
 
-After you have clicked ``Finish``, you will see the progress in the console for the tools getting installed. Once the installation is done, and if this is the very first set of ESP-IDF installed in the IDE, it will be activated as well. You will see a similar entry in the editor for ESP-IDF Manager:
+After the EIM is closed the ESP-IDF Manager editor will be updated with the latest information about the ESP-IDF versions and tools available.:
 
 .. image:: ../../media/ToolsManager/Tool_installed_and_activated.png
 
-You can add as many versions of ESP-IDF as you want, but only one version can be set as active, and that version will be used to compile and index projects in your workspace. This feature helps you switch between versions in the workspace easily.
+You can add as many versions of ESP-IDF as you want via EIM, but only one version can be set as active, and that version will be used to compile and index projects in your workspace. This feature helps you switch between versions in the workspace easily.
 
-Let's take a look at how multiple versions will look. Follow the same steps as before to add another ESP-IDF version to the IDE.
+To activate any specific version, simply click on the radio button next to it in the ``Active`` column.
 
-.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Multiple_versions.png
+The refresh button in the last column for the active ESP-IDF version can be used to reload any changes in the ESP-IDF directory you made.
 
-To activate any specific version, simply click on the radio button next to it in the ``Active`` column.
+.. note::
+    Any manual changes made to the ESP-IDF directory will not be reflected in the IDE until you refresh the active ESP-IDF version using the refresh button but if you made any changes to the installation of ESP-IDF using the EIM, those changes will be detected and a popup message will be shown to you to update the ESP-IDF version in the IDE.
+
+.. image:: ../../media/ToolsManager/ESP-IDF_Manager_Changed_Installation_Message.png
 
-The refresh button in the last column for the active ESP-IDF version can be used to reload any changes in the directory you made.
 
+Migrating Old Workspace to New
+-------------------------------
+.. _esp-idf-tools-migration:
+
+If you are migrating from an older version of the Espressif-IDE, you will need to convert your existing workspace to be 
+compatible with the new ESP-IDF Manager. 
+You will need to download and install the Espressif Installation Manager (EIM) from the following `link <https://dl.espressif.com/dl/eim/>`_. 
+After installation of the EIM please follow the steps below:
+
+1. Copy the downloaded EIM executable to `.espressif/eim_gui/` in user home directory for Windows and Linux.
+   For example, on Windows, it would be `C:\Users\<username>\.espressif\eim_gui\eim.exe`.
+   On Linux , it would be `~/.espressif/eim_gui/eim`.
+   For macOS, copy the downloaded `eim.app` to your `Applications`, for example, `/Applications/eim.app`.
+   
+2. Open the Espressif-IDE if already running restart it.
+3. After the IDE detects the EIM executable and a valid older workspace, it will prompt you to convert the old workspace to the new format.
+   .. image:: ../../media/ToolsManager/ESP-IDF_Manager_Convert_Old_Workspace.png
+4. Click on the ``Yes`` button to convert the old configuration. 
+5. Now in Espressif-IDE, go to ``Espressif > ESP-IDF Manager``.
+   The ESP-IDF Manager editor will open, and you can proceed to select activate against the version you want.
+   
 References
 ----------
 .. toctree::