Docs: Update and restructure documentation for upcoming release (v5.0.0) #51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: ESP32 Build and Test | |
| on: | |
| push: | |
| branches: [ main, develop ] | |
| pull_request: | |
| branches: [ main ] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| security-events: write | |
| issues: write | |
| pull-requests: write | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| strategy: | |
| matrix: | |
| environment: [esp32dev, adafruit_feather_esp32s3_tft, test] | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| - name: Cache pip | |
| uses: actions/cache@v4 | |
| with: | |
| path: ~/.cache/pip | |
| key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} | |
| restore-keys: | | |
| ${{ runner.os }}-pip- | |
| - name: Cache PlatformIO | |
| uses: actions/cache@v4 | |
| with: | |
| path: ~/.platformio | |
| key: ${{ runner.os }}-${{ hashFiles('**/lockfile') }} | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: '3.9' | |
| - name: Install PlatformIO | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install --upgrade platformio | |
| - name: Build ESP32 project | |
| run: pio run --environment ${{ matrix.environment }} | |
| - name: Run static analysis | |
| if: matrix.environment == 'esp32dev' | |
| run: pio check --environment ${{ matrix.environment }} --fail-on-defect=medium | |
| continue-on-error: true | |
| - name: Generate build report | |
| if: matrix.environment != 'test' | |
| run: | | |
| echo "## Build Report 📊" >> $GITHUB_STEP_SUMMARY | |
| echo "### Environment: ${{ matrix.environment }}" >> $GITHUB_STEP_SUMMARY | |
| echo "\`\`\`" >> $GITHUB_STEP_SUMMARY | |
| pio run --environment ${{ matrix.environment }} --verbose | grep -E "(RAM|Flash|Memory)" || echo "Memory usage information not available" | |
| echo "\`\`\`" >> $GITHUB_STEP_SUMMARY | |
| - name: Upload ESP32dev artifacts | |
| if: matrix.environment == 'esp32dev' | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: esp32dev-firmware | |
| path: | | |
| .pio/build/esp32dev/firmware.bin | |
| .pio/build/esp32dev/firmware.elf | |
| retention-days: 30 | |
| - name: Upload Feather ESP32-S3 artifacts | |
| if: matrix.environment == 'adafruit_feather_esp32s3_tft' | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: feather-esp32s3-firmware | |
| path: | | |
| .pio/build/adafruit_feather_esp32s3_tft/firmware.bin | |
| .pio/build/adafruit_feather_esp32s3_tft/firmware.elf | |
| retention-days: 30 | |
| documentation-check: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: '18' | |
| - name: Install markdownlint-cli | |
| run: npm install -g markdownlint-cli | |
| - name: Lint documentation | |
| run: | | |
| markdownlint *.md --ignore node_modules --config .markdownlint.json || true | |
| echo "## Documentation Check 📚" >> $GITHUB_STEP_SUMMARY | |
| echo "Markdown files linted successfully" >> $GITHUB_STEP_SUMMARY | |
| - name: Check documentation completeness | |
| run: | | |
| echo "## Documentation Files 📋" >> $GITHUB_STEP_SUMMARY | |
| echo "### Available Documentation:" >> $GITHUB_STEP_SUMMARY | |
| for file in *.md; do | |
| if [ -f "$file" ]; then | |
| echo "- ✅ $file ($(wc -l < "$file") lines)" >> $GITHUB_STEP_SUMMARY | |
| fi | |
| done | |
| size-analysis: | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: '3.9' | |
| - name: Install PlatformIO | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install --upgrade platformio | |
| - name: Build current version | |
| run: pio run --environment esp32dev | |
| - name: Get current build size | |
| run: | | |
| CURRENT_FLASH=$(pio run --environment esp32dev 2>&1 | grep -oP 'Flash:\s+\[.*?\]\s+\K[0-9.]+%' | tail -1) | |
| CURRENT_RAM=$(pio run --environment esp32dev 2>&1 | grep -oP 'RAM:\s+\[.*?\]\s+\K[0-9.]+%' | tail -1) | |
| echo "CURRENT_FLASH=${CURRENT_FLASH}" >> $GITHUB_ENV | |
| echo "CURRENT_RAM=${CURRENT_RAM}" >> $GITHUB_ENV | |
| - name: Checkout base branch | |
| run: | | |
| git fetch origin main | |
| git checkout origin/main | |
| - name: Build base version | |
| run: pio run --environment esp32dev | |
| - name: Get base build size | |
| run: | | |
| BASE_FLASH=$(pio run --environment esp32dev 2>&1 | grep -oP 'Flash:\s+\[.*?\]\s+\K[0-9.]+%' | tail -1) | |
| BASE_RAM=$(pio run --environment esp32dev 2>&1 | grep -oP 'RAM:\s+\[.*?\]\s+\K[0-9.]+%' | tail -1) | |
| echo "BASE_FLASH=${BASE_FLASH}" >> $GITHUB_ENV | |
| echo "BASE_RAM=${BASE_RAM}" >> $GITHUB_ENV | |
| - name: Display size comparison | |
| run: | | |
| echo "## 📊 Build Size Analysis" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "| Metric | Base (main) | Current | Change |" >> $GITHUB_STEP_SUMMARY | |
| echo "|--------|-------------|---------|--------|" >> $GITHUB_STEP_SUMMARY | |
| echo "| Flash Usage | ${BASE_FLASH} | ${CURRENT_FLASH} | $([ "${CURRENT_FLASH}" != "${BASE_FLASH}" ] && echo "⚠️ Changed" || echo "✅ No change") |" >> $GITHUB_STEP_SUMMARY | |
| echo "| RAM Usage | ${BASE_RAM} | ${CURRENT_RAM} | $([ "${CURRENT_RAM}" != "${BASE_RAM}" ] && echo "⚠️ Changed" || echo "✅ No change") |" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "### Analysis" >> $GITHUB_STEP_SUMMARY | |
| echo "- Flash usage: ${CURRENT_FLASH} (was ${BASE_FLASH})" >> $GITHUB_STEP_SUMMARY | |
| echo "- RAM usage: ${CURRENT_RAM} (was ${BASE_RAM})" >> $GITHUB_STEP_SUMMARY | |
| echo "- Changes in memory usage should be reviewed for optimization opportunities" >> $GITHUB_STEP_SUMMARY | |
| - name: Comment size comparison on PR | |
| if: github.event_name == 'pull_request' | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const currentFlash = process.env.CURRENT_FLASH || 'N/A'; | |
| const currentRam = process.env.CURRENT_RAM || 'N/A'; | |
| const baseFlash = process.env.BASE_FLASH || 'N/A'; | |
| const baseRam = process.env.BASE_RAM || 'N/A'; | |
| const body = `## 📊 Build Size Analysis | |
| | Metric | Base (main) | Current (PR) | Change | | |
| |--------|-------------|--------------|--------| | |
| | Flash Usage | ${baseFlash} | ${currentFlash} | ${currentFlash !== baseFlash ? '⚠️ Changed' : '✅ No change'} | | |
| | RAM Usage | ${baseRam} | ${currentRam} | ${currentRam !== baseRam ? '⚠️ Changed' : '✅ No change'} | | |
| ### Analysis | |
| - Flash usage shows the percentage of ESP32 flash memory used | |
| - RAM usage shows the percentage of runtime memory used | |
| - Changes in memory usage should be reviewed for optimization opportunities | |
| *This analysis helps maintain optimal memory usage across code changes.*`; | |
| github.rest.issues.createComment({ | |
| issue_number: context.issue.number, | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| body: body | |
| }); | |
| security-scan: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| - name: Run Trivy vulnerability scanner | |
| uses: aquasecurity/trivy-action@master | |
| with: | |
| scan-type: 'fs' | |
| scan-ref: '.' | |
| format: 'sarif' | |
| output: 'trivy-results.sarif' | |
| - name: Upload Trivy scan results to GitHub Security tab | |
| uses: github/codeql-action/upload-sarif@v3 | |
| if: always() | |
| with: | |
| sarif_file: 'trivy-results.sarif' |