docs_build.yml

name: Documentation Build and Deploy CI

on:
  release:
    types:
      - created
  push:
    branches:
      - master
      - release/*
    paths:
      - "docs/**"
      - ".github/workflows/docs_build.yml"
  pull_request:
    paths:
      - "docs/**"
      - ".github/workflows/docs_build.yml"
  workflow_dispatch:

jobs:
  build-docs:
    name: Build ESP-IDF Installation Manager 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
      - name: Deploy Documentation to production server
        if: github.event_name == 'release' && github.event.action == 'created'
        env:
          # Deploy to production server
          # DOCS_BUILD_DIR: "./docs/_build/"
          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 }}
          ESP_DOCS_LATEST_BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
        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