docs: Move documentation to docs.espressif #1076)

Move documentation to docs.espressif

.github/workflows/docs_build.yml

@@ -1,4 +1,4 @@
-name: Documentation Build and Deploy CI
+name: Documentation Build and Preview Deploy CI
 
 on:
   push:

.github/workflows/docs_production.yml

@@ -32,11 +32,11 @@ jobs:
       env:
         # Deploy to production server
         # DOCS_BUILD_DIR: "./docs/_build/"
-        DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PREVIEW_PRIVATEKEY }}
-        DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PREVIEW_PATH }}
-        DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PREVIEW_SERVER }}
-        DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PREVIEW_USER }}
-        DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_PREVIEW_URL_BASE }}
+        DOCS_DEPLOY_PRIVATEKEY: ${{ secrets.DOCS_PROD_PRIVATEKEY }}
+        DOCS_DEPLOY_PATH: ${{ secrets.DOCS_PROD_PATH }}
+        DOCS_DEPLOY_SERVER: ${{ secrets.DOCS_PROD_SERVER }}
+        DOCS_DEPLOY_SERVER_USER: ${{ secrets.DOCS_PROD_USER }}
+        DOCS_DEPLOY_URL_BASE: ${{ secrets.DOCS_PROD_URL_BASE }}
       run: |
         sudo apt update
         sudo apt install python3-pip python3-setuptools

.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);
+            }

FAQ.md

@@ -95,19 +95,6 @@ Check below links:
 - https://esp32.com/viewtopic.php?f=13&t=12327&start=10#p50137 
 - https://stackoverflow.com/questions/6908948/java-sun-security-provider-certpath-suncertpathbuilderexception-unable-to-find
 
-## Why Java 11 recommended for IDF Eclipse Plugin?
-We recommend using Java 11(that's the latest LTS version from Oracle) and above while working with IDF Eclipse Plugin considering Eclipse 2020-06 has a requirement for Java 11 to work with the CDT. Here are some important pointers from Eclipse.
-
-### Installing CDT 9.11 on Eclipse 2020-06 and later requires a workaround when using Java 8
-Check this - https://wiki.eclipse.org/CDT/User/NewIn911#Release
-
-CDT 9.11 only requires Java 8 to run. However, a new feature in Eclipse 2020-06 and later means that the install wizard may prevent installation. The workaround is to disable "Verify provisioning operation is compatible with currently running JRE" in Windows -> Preferences -> Install/Update. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=564407#c1
-
-### CDT 10.0 required Java 11 or later
-Check this - https://wiki.eclipse.org/CDT/User/NewIn100
-
-Starting with CDT 10.0 Java 11 or later is required to run CDT. This aligns with requirements of Eclipse IDE which also requires Java 11 to run starting in 2020-09.
-
 ## How to delete Launch Targets from the Eclipse
 There is no UI option to delete launch targets directly from the eclipse, however this can be achieved by following the below instructions.
 - Go to the Eclipse workspace directory. For example: In my case /Users/myName/myTesteclipseWorkspace

docs/en/additionalfeatures.rst

@@ -3,7 +3,21 @@ 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>
+
+

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/clangd_cdt_support.rst

@@ -0,0 +1,58 @@
+.. _clangd_cdt_support:
+
+Espressif-IDE LSP Support for C/C++ Editor
+==========================================
+
+The Espressif-IDE 3.0.0 (and higher) now includes the `Eclipse CDT-LSP <https://github.com/eclipse-cdt/cdt-lsp/>`, enabling support for the latest C/C++ standards and providing an LSP-based C/C++ Editor. This editor, powered by the `LLVM <https://clangd.llvm.org/>` clangd C/C++ language server, offers advanced functionality for ESP-IDF developers.
+
+In line with this enhancement, we've discontinued support for the standard CDT Editor/Indexer, as it only offers support for up to C++ 14. This has been replaced with a new LSP editor, especially considering that ESP-IDF now utilizes C++ 20 (with GCC 11.2) in v5.0.x, transitions to C++ 23 (with GCC 12.1) in v5.1, and to C++ 23 with GCC 13.1 in v5.2.
+
+The LSP powered C/C++ editor greatly benefits ESP-IDF developers by aligning with the latest language standards and compiler versions, enhancing productivity, and improving code quality.
+
+You can find more details on the LSP based C/C++ Editor features `here <https://github.com/eclipse-cdt/cdt-lsp/>`_.
+
+Prerequisites
+-------------
+* You need to have Espressif-IDE 3.0.0 (and higher) to have access to the LSP powered C/C++ editor.
+* If you are updating Eclipse CDT or Espressif-IDE via the update site, you need to select the ESP-IDF Eclipse Plugin and its dependencies, as shown below:
+
+  .. image:: ../../../media/clangd/cdtlsp_updatesite.png
+
+Clangd Configuration
+--------------------
+
+By default, the esp-clang toolchain is installed as a part of the ESP-IDF tools installation process, and clangd **Path** is configured in the preferences.
+
+The **Drivers** path and **--compile-commands-dir** path will be configured based on the selected target (esp32, esp32c6 etc.) and the project you're building.
+
+However, if there are any issues in configuration, this can be configured in the following way:
+
+1. Go to `Window` > `Preferences` > `C/C++` > `Editor(LSP)`
+2. Navigate to `clangd` node
+3. Provide `Drivers` path as shown in the screenshot.
+4. Set `--compile-commands-dir=/project/build` in the additional argument section.
+5. Click on `Apply and Close`.
+
+   .. image:: ../../../media/clangd/clangd_config.png
+
+By default, when you create a new project, a `.clangd` configuration file is created with the following arguments.
+
+However, if you are dealing with an existing project, please create a `.clangd` file at the root of the project and add the following content.
+
+.. code-block:: yaml
+
+    CompileFlags:
+      CompilationDatabase: build
+      Remove: [-m*, -f*]
+
+Disable CDT Indexer
+-------------------
+
+With Espressif-IDE 3.0.0 (and higher), the CDT Indexer is disabled by default; instead, the LSP Indexer server will be used for code analysis.
+
+If, for some reason, it is not disabled, please follow the steps below to disable it.
+
+1. Go to `Window` > `Preferences` > `C/C++` > `Indexer`
+2. Uncheck `Enable Indexer` option and then click on `Apply and Close`.
+
+   .. image:: ../../../media/clangd/cdt_indexer_disable.png

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