espressif · kolipakakondal · Jun 23, 2024 · Jun 20, 2024 · Jun 20, 2024 · Jun 20, 2024
diff --git a/.github/workflows/docs_build.yml b/.github/workflows/docs_build.yml
@@ -0,0 +1,69 @@
+name: Documentation Build and Deploy CI
+
+on:
+  push:
+    branches:
+    - master
+    - release/*
+    paths:
+    - 'docs/**'
+    - '.github/workflows/docs_build.yml'
+  pull_request:
+    paths:
+    - 'docs/**'
+    - '.github/workflows/docs_build.yml'
+
+jobs:
+
+  build-docs:
+    name: Build Espressif-IDE Docs
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+    - uses: actions/setup-python@v5
+      with:
+        cache-dependency-path: docs/requirements.txt
+        cache: 'pip'
+        python-version: '3.10'
+    - name: Build
+      run: |
+        sudo apt update
+        sudo apt install python3-pip python3-setuptools
+        # GitHub CI installs pip3 and setuptools outside the path.
+        # Update the path to include them and run.
+        cd ./docs
+        PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
+        PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en
+    - name: Archive Docs
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs
+        path: docs
+    - name: Deploy Documentation to preview server
+      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 }}
+      run: |
+        sudo apt update
+        sudo apt install python3-pip python3-setuptools
+        source ./docs/utils.sh
+        add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
+        export GIT_VER=$(git describe --always)
+        echo "PIP install requirements..."
+        pip3 install --user -r ./docs/requirements.txt
+        echo "Building the Docs..."
+        cd ./docs && build-docs -l en
+        echo "Deploy the Docs..."
+        export DOCS_BUILD_DIR=$GITHUB_WORKSPACE/docs/
+        cd $GITHUB_WORKSPACE/docs
+        deploy-docs
diff --git a/.github/workflows/docs_production.yml b/.github/workflows/docs_production.yml
@@ -0,0 +1,53 @@
+name: Documentation Build and Production Deploy CI
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+    - release/*
+    - master
+    paths:
+    - 'docs/**'
+    - '.github/workflows/docs_production.yml'
+
+jobs:
+
+  deploy-prod-docs:
+    name: Deploy Documentation on Production
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+    - uses: actions/setup-python@v5
+      with:
+        cache-dependency-path: docs/requirements.txt
+        cache: 'pip'
+        python-version: '3.10'
+    - name: Deploy Documentation
+      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 }}
+      run: |
+        sudo apt update
+        sudo apt install python3-pip python3-setuptools
+        source ./docs/utils.sh
+        add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
+        export GIT_VER=$(git describe --always)
+        echo "PIP install requirements..."
+        pip3 install --user -r ./docs/requirements.txt
+        echo "Building the Docs..."
+        cd ./docs && build-docs -l en
+        echo "Deploy the Docs..."
+        export DOCS_BUILD_DIR=$GITHUB_WORKSPACE/docs/
+        cd $GITHUB_WORKSPACE/docs
+        deploy-docs
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,10 @@
 /.DS_Store
 tests/com.espressif.idf.ui.test/target/classes/default-test.properties
 workspace/.metadata/.log
+/docs/_build/
+/docs/.DS_Store
+/docs/en/.DS_Store
+/docs/en/additionalfeatures/.DS_Store
+/.github/.DS_Store
+/docs/_static/.DS_Store
+
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+# Espressif-IDE 
+
+Espressif-IDE documentation using esp-docs.
diff --git a/docs/__pycache__/conf_common.cpython-312.pyc b/docs/__pycache__/conf_common.cpython-312.pyc
diff --git a/docs/_build/en/generic/html/_static/windows-logo.png b/docs/_build/en/generic/html/_static/windows-logo.png
diff --git a/docs/_static/windows-logo.png b/docs/_static/windows-logo.png
diff --git a/docs/conf_common.py b/docs/conf_common.py
@@ -0,0 +1,28 @@
+from esp_docs.conf_docs import *  # noqa: F403,F401
+from esp_docs.constants import TARGETS
+
+
+languages = ['en', 'zh_CN']
+
+extensions += ['sphinx_copybutton',
+               'sphinxcontrib.wavedrom',
+               ]
+
+# link roles config
+github_repo = 'espressif/esp-idf'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'idf-eclipse-plugin'
+
+html_static_path = ['../_static']
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-docs'
+
+# Contains info used for constructing target and version selector
+# Can also be hosted externally, see esp-idf for example
+versions_url = './_static/docs_version.js'
+
+# Final PDF filename will contains target and version
+pdf_file_prefix = u'espressif-ide'
diff --git a/docs/en/additionalfeatures.rst b/docs/en/additionalfeatures.rst
@@ -0,0 +1,9 @@
+Additional IDE Features
+===============================
+.. toctree::
+    :maxdepth: 1
+
+    ESP-IDF Application Size Analysis<additionalfeatures/application-size-analysis>
+    ESP-IDF Terminal<additionalfeatures/esp-terminal>
+    Install ESP-IDF Components<additionalfeatures/install-esp-components>
+
diff --git a/docs/en/additionalfeatures/application-size-analysis.rst b/docs/en/additionalfeatures/application-size-analysis.rst
@@ -0,0 +1,2 @@
+ESP-IDF Application Size Analysis
+===================================
diff --git a/docs/en/additionalfeatures/esp-terminal.rst b/docs/en/additionalfeatures/esp-terminal.rst
@@ -0,0 +1,2 @@
+ESP-IDF Terminal
+===============================
diff --git a/docs/en/additionalfeatures/install-esp-components.rst b/docs/en/additionalfeatures/install-esp-components.rst
@@ -0,0 +1,2 @@
+Install ESP-IDF Components
+===============================
diff --git a/docs/en/buildproject.rst b/docs/en/buildproject.rst
@@ -0,0 +1,2 @@
+Build the Project
+===============================
diff --git a/docs/en/conf.py b/docs/en/conf.py
@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'Espressif-IDE'
+copyright = u'2016 - 2024, Espressif Systems (Shanghai) Co., Ltd'
+pdf_title = u'Espressif-IDE Guide'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'
diff --git a/docs/en/configureproject.rst b/docs/en/configureproject.rst
@@ -0,0 +1,2 @@
+Configure Your Project
+===============================
diff --git a/docs/en/connectdevice.rst b/docs/en/connectdevice.rst
@@ -0,0 +1,2 @@
+Connect Your Device
+===============================
diff --git a/docs/en/debugproject.rst b/docs/en/debugproject.rst
@@ -0,0 +1,2 @@
+Debug Your Project
+===============================
diff --git a/docs/en/faqs.rst b/docs/en/faqs.rst
@@ -0,0 +1,2 @@
+FAQs
+===============================
diff --git a/docs/en/flashdevice.rst b/docs/en/flashdevice.rst
@@ -0,0 +1,2 @@
+Flash onto the Device
+===============================
diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -0,0 +1,52 @@
+Espressif-IDE
+=========================
+:link_to_translation:`zh_CN:[中文]`
+
+Espressif-IDE is an Integrated Development Environment(IDE) based on Eclipse CDT for developing IoT Applications using the ESP-IDF framework. It's a standalone and customized IDE built specifically for ESP-IDF. Espressif-IDE comes with the IDF Eclipse plugins, essential Eclipse CDT plugins, and other third-party plugins from the Eclipse platform to support building ESP-IDF applications.
+
+The plug-in runs on macOS, Windows and Linux platforms.
+
+Features
+----------------
+
+- Easy-to-use IDE built on Eclipse CDT environment
+- Specifically built for ESP-IDF application development
+- Auto-configuration of the build environment variables
+- Integrated toolchain configuration
+- New Project Wizards and getting started ESP-IDF examples
+- Advanced editing, compiling, and editing with syntax coloring features
+- Pre-built function header and function definition navigation
+- ESP-IDF and ESP-IDF Tools installation and configuration directly from IDE
+- SDK Configuration editor for project-specific settings
+- Integrated CMake Editor plug-in for editing CMake files such as CMakeLists.txt
+- CMake based build support
+- Support for UART and JTAG flashing
+- Customized ESP-IDF OpenOCD Debugging with pre-built configuration and settings
+- GDB Hardware debugging
+- Integrated ESP-IDF serial monitor
+- ESP-IDF Terminal with the pre-configured ESP-IDF build environment
+- Application size analysis editor for analyzing static memory footprint of your application
+- Supports Heap profiling for memory analysis and finding memory leaks
+- Supports GDB Stub debugging and Application level tracing
+- Supports esp32,esp32s2, esp32s3 and esp32c3 chips
+- English and Chinese language support for IDE
+- Extensible IDE for other third-party plugins from Eclipse eco-system
+- Host operating systems supported: Windows, macOS, and Linux
+
+
+For more about this project please see https://github.com/espressif/idf-eclipse-plugin
+
+.. toctree::
+    :maxdepth: 1
+
+    Prerequisites <prerequisites>
+    Installation <installation>
+    Start a Project<startproject>
+    Connect Your Device<connectdevice>
+    Build the Project<buildproject>
+    Configure Your Project<configureproject>
+    Flash onto the Device<flashdevice>
+    Monitor the Output<monitoroutput>
+    Debug Your Project<debugproject>
+    Additional IDE Features<additionalfeatures>
+    FAQs<faqs>
diff --git a/docs/en/installation.rst b/docs/en/installation.rst
@@ -0,0 +1,16 @@
+Installation
+===============================
+We recommend using the Espressif-IDE instead of the Eclipse CDT + IEP Plugin update approach to avoid the hassles of updating.
+
+Windows
+-------------------------
+Download the Espressif-IDE with ESP-IDF Offline Windows Installer and follow the instructions provided here. This guide will walk you through the installation process for Java, Git, CMake, ESP-IDF, IDF Tools, Device Drivers, and Espressif-IDE to help you get started.
+
+macOS
+---------------------------------
+To begin, download the Espressif-IDE for your respective operating system. Following this, launch the IDE and proceed to install the necessary ESP-IDF and related tools. Please note that prior to launching the IDE, you must ensure that Java, Python, and Git are installed as prerequisites. and available in the system path.
+If you plan to use Eclipse CDT and update it through the IDF Eclipse plugin, please ensure that you download the supported version for your operating system from here.
+
+Linux
+---------------------------------
+Linux specific documentation here.
diff --git a/docs/en/monitoroutput.rst b/docs/en/monitoroutput.rst
@@ -0,0 +1,2 @@
+Monitor the Output
+===============================
diff --git a/docs/en/prerequisites.rst b/docs/en/prerequisites.rst
@@ -0,0 +1,9 @@
+Prerequisites
+===============================
+The minimum requirements for running the Espressif-IDE are below.
+
+- `Java 17 <https://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ and above.
+- `Python 3.8 <https://www.python.org/downloads/>`_ and above.
+- `Git <https://git-scm.com/downloads>`_.
+
+Note: Make sure Java, Python and Git are available on the environment PATH.
diff --git a/docs/en/startproject.rst b/docs/en/startproject.rst
@@ -0,0 +1,2 @@
+Start a Project
+===============================
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+esp-docs>=1.4.0
+sphinx-copybutton==0.5.0
+sphinx-tabs==3.2.0
diff --git a/docs/utils.sh b/docs/utils.sh
@@ -0,0 +1,18 @@
+# Bash helper functions for adding SSH keys
+
+function add_ssh_keys() {
+  local key_string="${1}"
+  mkdir -p ~/.ssh
+  chmod 700 ~/.ssh
+  echo -n "${key_string}" >~/.ssh/id_rsa_base64
+  base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 >~/.ssh/id_rsa
+  chmod 600 ~/.ssh/id_rsa
+}
+
+function add_doc_server_ssh_keys() {
+  local key_string="${1}"
+  local server_url="${2}"
+  local server_user="${3}"
+  add_ssh_keys "${key_string}"
+  echo -e "Host ${server_url}\n\tStrictHostKeyChecking no\n\tUser ${server_user}\n" >>~/.ssh/config
+}