Docs migration

.github/workflows/pr-comment.yml

@@ -0,0 +1,62 @@
+name: Comment on pull request
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+jobs:
+  pr_comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          # This snippet is public-domain, taken from
+          # https://github.com/oprypin/nightly.link/blob/master/.github/workflows/pr-comment.yml
+          script: |
+            async function upsertComment(owner, repo, issue_number, purpose, body) {
+              const {data: comments} = await github.rest.issues.listComments(
+                {owner, repo, issue_number});
+
+              const marker = `<!-- bot: ${purpose} -->`;
+              body = marker + "\n" + body;
+
+              const existing = comments.filter((c) => c.body.includes(marker));
+              if (existing.length > 0) {
+                const last = existing[existing.length - 1];
+                core.info(`Updating comment ${last.id}`);
+                await github.rest.issues.updateComment({
+                  owner, repo,
+                  body,
+                  comment_id: last.id,
+                });
+              } else {
+                core.info(`Creating a comment in issue / PR #${issue_number}`);
+                await github.rest.issues.createComment({issue_number, body, owner, repo});
+              }
+            }
+
+            const {owner, repo} = context.repo;
+            const run_id = ${{github.event.workflow_run.id}};
+
+            const pull_requests = ${{ toJSON(github.event.workflow_run.pull_requests) }};
+            if (!pull_requests.length) {
+              return core.error("This workflow doesn't match any pull requests!");
+            }
+
+            const artifacts = await github.paginate(
+              github.rest.actions.listWorkflowRunArtifacts, {owner, repo, run_id});
+            if (!artifacts.length) {
+              return core.error(`No artifacts found`);
+            }
+            let body = `Download the artifacts for this pull request:\n`;
+            for (const art of artifacts) {
+              body += `\n* [${art.name}.zip](https://nightly.link/${owner}/${repo}/actions/artifacts/${art.id}.zip)`;
+            }
+
+            core.info("Review thread message body:", body);
+
+            for (const pr of pull_requests) {
+              body += `\n [Espressif-IDE Documentation Preview](https://preview-docs.espressif.com/projects/espressif-ide/en/${pr.number}-merge/index.html)`;
+              await upsertComment(owner, repo, pr.number,
+                "nightly-link", body);
+            }

docs/en/additionalfeatures.rst

@@ -3,7 +3,23 @@ Additional IDE Features
 .. toctree::
     :maxdepth: 1
 
+    LSP C/C++ Editor<additionalfeatures/lspeditor>
+    CMake Editor<additionalfeatures/cmakeeditor>
     ESP-IDF Application Size Analysis<additionalfeatures/application-size-analysis>
     ESP-IDF Terminal<additionalfeatures/esp-terminal>
     Install ESP-IDF Components<additionalfeatures/install-esp-components>
-
+    Heap Tracing<additionalfeatures/heaptracing>
+    ESP-IDF OpenOCD Debugging<openocddebugging>
+    GDB Stub Debugging<additionalfeatures/gdbstubdebugging>
+    Core Dump Debugging<additionalfeatures/coredumpdebugging>
+    Application Level Tracing<additionalfeatures/appleveltracing>
+    Partition Table Editor<additionalfeatures/partitiontableeditor>
+    NVS Partition Editor<additionalfeatures/nvspartitioneditor>
+    Write Binary to Flash<additionalfeatures/writebinarytoflash>
+    DFU Flashing<additionalfeatures/dfu>
+    Wokwi Simulator<additionalfeatures/wokwisimulator>
+    Switch Between Languages<additionalfeatures/switchlanguage>
+    Configure CDT Build Environment Variables<additionalfeatures/configureenvvariables>
+    Configuring Clang Toolchain<additionalfeatures/clangtoolchain>
+    Update Site Installation Guide<marketplaceupdate>
+    Windows Offline Installer<windowsofflineinstaller>

docs/en/additionalfeatures/appleveltracing.rst

@@ -0,0 +1,47 @@
+Application Level Tracing
+=========================
+
+ESP-IDF provides a useful feature for program behavior analysis called `Application Level Tracing <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/app_trace.html?>`_. The IDF-Eclipse plugin has a UI that allows you to start and stop tracing commands and process the received data. To familiarize yourself with this library, you can use the `app_trace_to_host <https://github.com/espressif/esp-idf/tree/release/v5.0/examples/system/app_trace_to_host>`_ project or the `app_trace_basic <https://github.com/espressif/esp-idf/tree/release/v5.1/examples/system/app_trace_basic>`_ project (if using esp-idf 5.1 and higher). These projects can be created from the plugin itself:
+
+.. image::  ../../../media/AppLvlTracing_1.png
+   :alt: Application Level Tracing project creation
+
+Before using application-level tracing, create a debug configuration for the project where you must select the board you are using to successfully start the OpenOCD server.
+
+.. image::  ../../../media/AppLvlTracing_3.png
+   :alt: Debug configuration setup
+
+After creating the debug configuration, right-click on the project in the Project Explorer and select *ESP-IDF > Application Level Tracing*:
+
+.. image::  ../../../media/AppLvlTracing_2.png
+   :alt: Application Level Tracing option in the context menu
+
+It may take a moment to open the application level tracing dialog, as the OpenOCD server starts first. At the top of the dialog, you will find auto-configured fields that you can adjust for the trace start command.
+
+**Start Command:**
+
+- Syntax: ``start <outfile> [poll_period [trace_size [stop_tmo [wait4halt [skip_size]]]]``
+- Arguments:
+  - ``outfile``: Path to the file where data from both CPUs will be saved, with format ``file://path/to/file``.
+  - ``poll_period``: Data polling period (in ms). If greater than 0, the command runs in non-blocking mode. Default: 1 ms.
+  - ``trace_size``: Maximum data size to collect (in bytes). Tracing stops after the specified amount of data is received. Default: -1 (disabled).
+  - ``stop_tmo``: Idle timeout (in sec). Stops tracing if there is no data for the specified period. Default: -1 (disabled).
+  - ``wait4halt``: If 0, tracing starts immediately; otherwise, waits for the target to halt before starting. Default: 0.
+  - ``skip_size``: Bytes to skip at the start. Default: 0.
+
+Additional information can be found `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/app_trace.html?>`_.
+
+.. image::  ../../../media/AppLvlTracing_4.png
+   :alt: Application Level Tracing dialog
+
+The next two fields, *Trace Processing Script* and *Start Parsing Command*, are used to parse the output file.
+
+- **Trace Processing Script**: Path to the parsing script, which by default is ``logtrace_proc.py`` from esp-idf.
+- **Start Parsing Command**: Allows you to check and edit the parsing command if necessary. By default, it is configured as: ``$IDF_PATH/tools/esp_app_trace/logtrace_proc.py/path/to/trace/file/path/to/program/elf/file``.
+
+The *Start parse* button is disabled until a dump file is generated. To generate it, click the *Start* button at the bottom of the dialog box. This button changes to *Stop* once tracing starts, allowing you to stop it.
+
+When the output file is available, click *Start parse* to view the parsed script output in the Eclipse console:
+
+.. image::  ../../../media/AppLvlTracing_5.png
+   :alt: Parsed script output in Eclipse console

docs/en/additionalfeatures/application-size-analysis.rst

@@ -1,2 +1,24 @@
 ESP-IDF Application Size Analysis
 ===================================
+
+The Application Size Analysis editor provides a way to analyze the static memory footprint of your application. It has two sections:
+
+- The **Overview** section provides a summary of the application's memory usage;
+- The **Details** section includes in-depth details about components and per-symbol level memory information.
+
+The **Details** table viewer also provides searching and sorting capabilities on various columns.
+
+To launch the Application Size Analysis editor:
+
+#. Right-click on the project.
+#. Select **ESP-IDF > Application Size Analysis** menu option to launch the editor.
+
+**Application Size Analysis - Overview**
+
+.. image:: ../../../media/sizeanalysis_overview.png
+   :alt: Application Size Analysis - Overview
+
+**Application Size Analysis - Details**
+
+.. image:: ../../../media/sizeanalysis_details.png
+   :alt: Application Size Analysis - Details

docs/en/additionalfeatures/clangtoolchain.rst

@@ -0,0 +1,15 @@
+Configuring Clang Toolchain
+===========================
+
+1. After creating a new project, edit the project configuration.
+
+   .. image:: https://user-images.githubusercontent.com/24419842/194882285-9faadb5d-0fe2-4012-bb6e-bc23dedbdbd2.png
+      :alt: Project Configuration
+
+2. Go to the ``Build Settings`` tab and select the clang toolchain:
+
+   .. image:: https://user-images.githubusercontent.com/24419842/194882462-3c0fd660-b223-4caf-964d-58224d91b518.png
+      :alt: Clang Toolchain Selection
+
+.. note:: 
+   Clang toolchain is currently an experimental feature, and you may encounter build issues due to incompatibility with ESP-IDF. The following describes how to address the most common build issues on the current ESP-IDF master (ESP-IDF v5.1-dev-992-gaf28c1fa21-dirty). To work around clang build errors, please refer to `this workaround guide <https://github.com/espressif/idf-eclipse-plugin/blob/master/WORKAROUNDS.md#clang-toolchain-buid-errors>`_.

docs/en/additionalfeatures/cmakeeditor.rst

@@ -0,0 +1,12 @@
+CMake Editor
+============
+
+The CMake Editor Plug-in is integrated with the IDF Plugin for editing CMake files, such as ``CMakeLists.txt``. It provides syntax coloring, CMake command content assistance, and code templates.
+
+.. image:: ../../../media/cmake_editor_ca.png
+   :alt: CMake Editor with content assist
+
+CMake editor preferences can be controlled using **Eclipse > Preferences > CMakeEd**.
+
+.. image:: ../../../media/cmake_editor_preferences.png
+   :alt: CMake editor preferences

docs/en/additionalfeatures/configureenvvariables.rst

@@ -0,0 +1,7 @@
+Configuring Environment Variables
+==================================
+
+All the required environment variables are automatically configured by the IDE during the ESP-IDF and Tools installation process (``Espressif > ESP-IDF Manager > Add ESP-IDF``). You can verify these variables in the Preferences page under ``C/C++ > Build > Environment``.
+
+.. image:: ../../../media/2_environment_pref.png
+   :alt: Environment Preferences

docs/en/additionalfeatures/coredumpdebugging.rst

@@ -0,0 +1,20 @@
+.. _coredumpdebugging:
+
+Core Dump Debugging
+====================
+
+The IDF-Eclipse plugin allows you to debug the core dump if any crash occurs on the chip and the configurations are set. Currently, only the UART core dump capture and debugging is supported.
+
+To enable core dump debugging for a project:
+
+1. You need to enable it first in `sdkconfig`. Launch the `sdkconfig` in the project root by double-clicking on it which will open the configuration editor.
+
+2. Click on the `Core Dump` from the settings on the left and select `Data Destination` as `UART`.
+
+.. image:: ../../../media/CoreDumpDebugging/sdkconfig_editor.png
+
+This will enable the core dump debugging, and whenever you connect a serial monitor for that project, if any crash occurs, it will load the dump and open a debug perspective in Eclipse to let you diagnose the dump where you can view all the information in the core dump.
+
+You can view the registers stack trace and even view the value of variables in the stack frame.
+
+To exit the debug session: simply press the `stop` button.

docs/en/additionalfeatures/dfu.rst

@@ -0,0 +1,42 @@
+.. _dfuflashing:
+
+Device Firmware Upgrade (DFU) through USB
+==========================================
+
+Device Firmware Upgrade (DFU) is a mechanism for upgrading the firmware of devices through Universal Serial Bus (USB). There are a few requirements that need to be met:
+
+- DFU is supported by ESP32-S2 and ESP32-S3 chips.
+- You will need to do some electrical connection work. Here is a `guide <https://blog.espressif.com/dfu-using-the-native-usb-on-esp32-s2-for-flashing-the-firmware-b2c4af3335f1>`_ for the ESP32-S2 board. The necessary connections for the USB peripheral are shown in the following table.
+
++------+---------------+
+| GPIO | USB           |
++======+===============+
+| 20   | D+ (green)    |
++------+---------------+
+| 19   | D- (white)    |
++------+---------------+
+| GND  | GND (black)   |
++------+---------------+
+| +5V  | +5V (red)     |
++------+---------------+
+
+After meeting the above requirements:
+
+1. The chip needs to be in bootloader mode for detection as a DFU device and flashing. This can be achieved by pulling GPIO0 down (e.g., pressing the BOOT button), pulsing RESET down for a moment, and releasing GPIO0.
+2. Install USB drivers (Windows only). The drivers can be installed by the `Zadig tool <https://zadig.akeo.ie/>`_.
+   - Ensure that the device is in download mode before running the tool and that it detects the device before installing the drivers.
+   - The Zadig tool might detect several USB interfaces of the target. Install the WinUSB driver only for the interface without a driver installed (likely Interface 2), and avoid re-installing drivers for other interfaces.
+   - Manual driver installation via Device Manager in Windows is not recommended, as it might cause flashing issues.
+
+After meeting the above requirements, you can proceed to build and flash via DFU. To use DFU:
+
+1. Edit the active launch configuration.
+2. In the main tab, select the *Flash over DFU* option.
+3. Select a suitable IDF target for DFU.
+4. When using the build command, an extra file (``dfu.bin``) will be created, which can be used later for flashing.
+
+.. image:: https://user-images.githubusercontent.com/24419842/226182180-286099d3-9c1c-4394-abb0-212d43054529.png
+   :alt: DFU actions
+
+Additional information, including common errors and known issues, is available in `this <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/dfu.html#usb-drivers-windows-only>`_.
+

docs/en/additionalfeatures/esp-terminal.rst

@@ -1,2 +1,14 @@
 ESP-IDF Terminal
 ===============================
+
+This would launch a local terminal with all the environment variables set under ``Preferences`` > ``C/C++`` > ``Build`` > ``Environment``. The default working directory would be either the currently selected project or ``IDF_PATH`` if there is no project selected.
+
+The terminal ``PATH`` is also configured with ``esptool``, ``espcoredump``, ``partition_table``, and ``app_update`` component paths, so it is convenient to access them directly from the ESP-IDF terminal.
+
+To launch the ESP-IDF Terminal:
+
+- Click on the ``Open a Terminal`` icon from the toolbar.
+- Choose ``ESP-IDF Terminal`` from the terminal drop-down and click ``OK`` to launch a terminal.
+
+.. image:: ../../../media/idf_terminal.png
+   :alt: ESP-IDF Terminal

docs/en/additionalfeatures/gdbstubdebugging.rst

@@ -0,0 +1,48 @@
+.. _gdbstubdebugging:
+
+GDBStub Debugging
+=================
+You can now use the GDBStub debugging inside our Eclipse plugin to help you diagnose and debug issues on chips via Eclipse when it is in panic mode.
+
+To enable GDBStub debugging for a project:
+
+1. Launch the `sdkconfig` in project root by double-clicking on it which will open the configuration editor.
+
+.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor.png
+
+2. Expand the `Component Config` section and select `ESP System Settings`. From the settings on the right for `Panic Handler behaviour` select the `GDBStub on Panic option` from the list.
+
+.. image:: ../../../media/GDBStubDebugging/sdkconfig_editor_panic_behavior.png
+
+Now you will be taken to the GDBStub debugger automatically when you connect the serial monitor and there is a panic for this example.
+
+To use the GDBStub debugging for a project:
+
+1. Create a template `hello_world` project and add the following lines in the main C file:
+
+   .. code-block:: c
+
+      This is a global variable<br/>
+      COREDUMP_DRAM_ATTR uint8_t global_var;
+
+2. Now add these two lines just above the `esp_restart()` function:
+
+   .. code-block:: c
+
+      global_var = 25;
+      assert(0);
+
+The final file should be something like this:
+
+.. image:: ../../../media/GDBStubDebugging/code_example.png
+
+Build and flash the project and launch the serial monitor. On line number 45, we are signaling for a failing assert which will put the chip in panic mode and when that line reaches, you will be prompted to switch the perspective to debug mode and the chip will be halted.
+
+Remember that this is a panic mode and you cannot continue the execution from here, you will have to stop and restart the chip through IDF commands or simply restart the serial monitor.
+
+.. image:: ../../../media/GDBStubDebugging/debug_panic_mode.png
+
+You can view the registers stack trace and even view the value of variables in the stack frame.
+
+To exit the debug session simply press the `stop` button.
+