docs: Move documentation to docs.espressif #1076)

Move documentation to docs.espressif

Author: kolipakakondal

.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