[CI] Refactor GitHub Actions workflows for build, documentation, and linting (#2260)

* Refactor GitHub Actions workflows for build, documentation, and linting

- Consolidated build logic into reusable workflows (`task-build.yml` and `task-docs.yml`) to reduce duplication across multiple workflows.
- Introduced `environments.json` to centralize the list of PlatformIO build environments, improving maintainability and clarity.
- Updated `build.yml` and `build_and_docs_to_dev.yml` to utilize the new reusable workflows and environment definitions.
- Enhanced `release.yml` to streamline the release process and integrate documentation generation.
- Created reusable linting workflow (`task-lint.yml`) to standardize code formatting checks across the repository.
- Simplified manual documentation workflow by leveraging the new reusable documentation workflow.
- Improved artifact management and retention policies across workflows.
- Updated dependencies and versions in workflows to ensure compatibility and performance.

* CI/CD pipeline agnostic of Workflow Engine and integrated on github actions

- Implemented ci.sh for orchestrating the complete build pipeline.
- Created ci_00_config.sh for centralized configuration of build scripts.
- Created ci_build_firmware.sh for building firmware for specified PlatformIO environments.
- Created ci_prepare_artifacts.sh for preparing firmware artifacts for upload or deployment.
- Created ci_set_version.sh for updating version tags in firmware configuration files.
- Created ci_build.sh to orchestrate the complete build pipeline.
- Created ci_qa.sh for code linting and formatting checks using clang-format.
- Created ci_site.sh for building and deploying VuePress documentation with version management.
- Implemented checks for required tools and dependencies in the new scripts.
- Updated common_wu.py, compressFirmware.py, gen_wu.py, generate_board_docs.py, and prepare_deploy.sh with descriptive comments.

Refactor CI/CD scripts for improved modularity and clarity

- Consolidated build steps in task-build.yml to utilize ci.sh for version tagging, building, and artifact preparation.
- Updated task-lint.yml to use ci.sh for code formatting checks instead of ci_qa.sh.
- Enhanced CI_SCRIPTS.md documentation to reflect changes in script usage, command structure, and output organization.
- Improved internal scripts for better error handling and logging.
- Streamlined the output structure for build artifacts and documentation.

.github/workflows/release.yml

@@ -5,47 +5,107 @@ on:
     types: [published]
 
 jobs:
-  build-upload:
+  prepare:
     runs-on: ubuntu-latest
-    name: Build and upload Assets to Release
+    outputs:
+      version-tag: ${{ steps.extract-tag.outputs.version }}
+      release-id: ${{ steps.extract-release.outputs.id }}
+      upload-url: ${{ steps.extract-release.outputs.upload_url }}
+    steps:
+      - name: Extract version tag
+        id: extract-tag
+        run: |
+          VERSION_TAG=${GITHUB_REF#refs/tags/}
+          echo "version=${VERSION_TAG}" >> $GITHUB_OUTPUT
+          echo "Extracted version: ${VERSION_TAG}"
+      
+      - name: Extract release info
+        id: extract-release
+        run: |
+          RELEASE_ID=$(jq --raw-output '.release.id' $GITHUB_EVENT_PATH)
+          UPLOAD_URL="https://uploads.github.com/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets{?name,label}"
+          echo "id=${RELEASE_ID}" >> $GITHUB_OUTPUT
+          echo "upload_url=${UPLOAD_URL}" >> $GITHUB_OUTPUT
+          echo "Release ID: ${RELEASE_ID}"
+
+  build:
+    needs: prepare
+    name: Build release firmware
+    uses: ./.github/workflows/task-build.yml
+    with:
+      python-version: '3.13'
+      enable-dev-ota: false
+      version-tag: ${{ needs.prepare.outputs.version-tag }}
+      artifact-retention-days: 90
+      artifact-name-prefix: 'firmware-'
+      prepare-for-deploy: true
+
+  deploy:
+    needs: [prepare, build]
+    runs-on: ubuntu-latest
+    name: Deploy release assets
     steps:
       - uses: actions/checkout@v4
+
+      - name: Download all firmware artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: firmware-*
+          path: .pio/build
+          merge-multiple: false
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.13"
+
       - name: Install uv
         uses: astral-sh/setup-uv@v6
         with:
           version: "latest"
           enable-cache: false
+
       - name: Install platformio
         run: |
           uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.18.zip
-      - name: Set version tag from git
-        run: sed -i "s/version_tag/${GITHUB_REF#refs/tags/}/g" main/User_config.h scripts/latest_version.json
-      - name: Extract ESP32 platform version from platformio.ini
+
+      - name: Reorganize artifacts for prepare_deploy.sh
         run: |
-          ESP32_VERSION=$(grep 'esp32_platform\s*=' platformio.ini | cut -d'@' -f2 | tr -d '[:space:]')
-          echo "ESP32_PLATFORM_VERSION=${ESP32_VERSION}" >> $GITHUB_ENV
-      - name: Run PlatformIO
-        run: platformio run
+          # Move artifacts from download structure to expected .pio/build structure
+          for env_dir in .pio/build/firmware-*; do
+            if [ -d "$env_dir" ]; then
+              env_name=$(basename "$env_dir" | sed 's/^firmware-//')
+              mkdir -p ".pio/build/${env_name}"
+              mv "$env_dir"/*.bin ".pio/build/${env_name}/" 2>/dev/null || true
+              rm -rf "$env_dir"
+            fi
+          done
+
       - name: Prepare Release Assets
         run: |
           sudo apt install rename
           ./scripts/prepare_deploy.sh
-      - name: Get upload url
-        id: release-id
-        run: |
-          RELEASE_ID=$(jq --raw-output '.release.id' $GITHUB_EVENT_PATH)
-          echo "::set-output name=upload_url::https://uploads.github.com/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets{?name,label}"
+
       - name: Upload Release Assets
         uses: bgpat/release-asset-action@03b0c30db1c4031ce3474740b0e4275cd7e126a3
         with:
           pattern: "toDeploy/*"
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          release-url: ${{ steps.release-id.outputs.upload_url }}
+          release-url: ${{ needs.prepare.outputs.upload-url }}
           allow-overwrite: true
-  call-workflow-passing-data:
-    needs: build-upload
-    uses: ./.github/workflows/manual_docs.yml
+
+  documentation:
+    needs: [prepare, deploy]
+    name: Build and deploy release documentation
+    uses: ./.github/workflows/task-docs.yml
+    with:
+      python-version: '3.11'
+      node-version: '18.x'
+      version-source: 'git-tag'
+      base-path: '/'
+      destination-dir: '.'
+      generate-webuploader: true
+      run-pagespeed: false
+    secrets:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      APIKEY: ${{ secrets.APIKEY }}