docs: move docs to https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/

.github/workflows/docs_build.yml

@@ -0,0 +1,69 @@
+name: Documentation Build and Deploy CI
+
+on:
+  push:
+    branches:
+    - master
+    - release/*
+    paths:
+    - 'docs_espressif/**'
+    - '.github/workflows/docs_build.yml'
+  pull_request:
+    paths:
+    - 'docs_espressif/**'
+    - '.github/workflows/docs_build.yml'
+
+jobs:
+
+  build-docs:
+    name: Build ESP-IDF VSCode Extension 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_espressif/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_espressif
+        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_espressif/_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_espressif/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_espressif/requirements.txt
+        echo "Building the Docs..."
+        cd ./docs_espressif && build-docs -l en
+        echo "Deploy the Docs..."
+        export DOCS_BUILD_DIR=$GITHUB_WORKSPACE/docs_espressif/
+        cd $GITHUB_WORKSPACE/docs_espressif
+        deploy-docs

.gitignore

@@ -18,4 +18,9 @@ flake8_output.txt
 results/
 report.txt
 report.json
-test-resources/**
+test-resources/**
+/docs_espressif/_build/
+/docs_espressif/.DS_Store
+/docs_espressif/en/.DS_Store
+/docs_espressif/en/additionalfeatures/.DS_Store
+/docs_espressif/_static/.DS_Store

.prettierignore

@@ -27,3 +27,4 @@ media/
 esp_debug_adapter/
 external/
 test-resources/
+docs_espressif/

docs_espressif/README.md

@@ -0,0 +1,3 @@
+# VS Code extension for ESP-IDF
+
+VS Code extension for ESP-IDF projects.

docs_espressif/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'] = 'vscode-esp-idf-extension'
+
+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'vscode-esp-idf-extension'

docs_espressif/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>
+

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

@@ -0,0 +1,2 @@
+ESP-IDF Application Size Analysis
+===================================

docs_espressif/en/additionalfeatures/esp-terminal.rst

@@ -0,0 +1,2 @@
+ESP-IDF Terminal
+===============================

docs_espressif/en/additionalfeatures/install-esp-components.rst

@@ -0,0 +1,2 @@
+Install ESP-IDF Components
+===============================

docs_espressif/en/buildproject.rst

@@ -0,0 +1,2 @@
+Build the Project
+===============================

docs_espressif/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'ESP-IDF Extension for VSCode'
+copyright = u'2016 - 2024, Espressif Systems (Shanghai) Co., Ltd'
+pdf_title = u'Guide for ESP-IDF Extension for VSCode'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

docs_espressif/en/configureproject.rst

@@ -0,0 +1,2 @@
+Configure Your Project
+===============================

docs_espressif/en/connectdevice.rst

@@ -0,0 +1,2 @@
+Connect Your Device
+===============================

docs_espressif/en/debugproject.rst

@@ -0,0 +1,2 @@
+Debug Your Project
+===============================

docs_espressif/en/faqs.rst

@@ -0,0 +1,2 @@
+FAQs
+===============================

docs_espressif/en/flashdevice.rst

@@ -0,0 +1,2 @@
+Flash onto the Device
+===============================

docs_espressif/en/index.rst

@@ -0,0 +1,28 @@
+ESP-IDF Extension for VSCode
+=============================
+:link_to_translation:`zh_CN:[中文]`
+
+The ESP-IDF Extension for VSCode Code empowers developers to efficiently develop, build, flash, monitor, debug, and manage projects targeting Espressif chips using the Espressif IoT Development Framework (ESP-IDF). This extension integrates seamlessly with Visual Studio Code, providing a familiar environment for streamlined development workflows. Whether you are a beginner or an experienced developer, this documentation will guide you through the process of setting up, configuring, and utilizing the ESP-IDF Extension to leverage the full potential of Espressif chips in your IoT applications.
+
+Features
+----------------
+
+Supported features by the ESP-IDF Extension here!
+
+
+For more about this project please see https://github.com/espressif/vscode-esp-idf-extension
+
+.. 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>

docs_espressif/en/installation.rst

@@ -0,0 +1,16 @@
+Installation
+===============================
+ESP-IDF VSCode Extension installation process here.
+
+Windows
+-------------------------
+Windows specific instructions here.
+
+macOS
+---------------------------------
+macOS specific installation here.
+
+
+Linux
+---------------------------------
+Linux specific documentation here.

docs_espressif/en/monitoroutput.rst

@@ -0,0 +1,2 @@
+Monitor the Output
+===============================

docs_espressif/en/prerequisites.rst

@@ -0,0 +1,6 @@
+Prerequisites
+===============================
+The minimum requirements for running the ESP-IDF Extension with the VSCode are below.
+
+- `Python 3.12 <https://www.python.org/downloads/>`_ and above.
+- `Git <https://git-scm.com/downloads>`_.

docs_espressif/en/startproject.rst

@@ -0,0 +1,2 @@
+Start a Project
+===============================

docs_espressif/requirements.txt

@@ -0,0 +1,3 @@
+esp-docs>=1.4.0
+sphinx-copybutton==0.5.0
+sphinx-tabs==3.2.0

docs_espressif/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
+}