build-docs.yml

name: Generate SDK Docs
on: 
  push:
    branches: ['main']

jobs:
  build-jekyll:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: 'true'
      - name: Build Jekyll
        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1
      - name: Upload Jekyll Artifact
        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
        with:
          name: jekyll-site
          path: _site

  build-docc:
    needs: build-jekyll
    runs-on: macos-15
    timeout-minutes: 10
    permissions: read-all
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: 'true'
      - name: Download Jekyll Artifact
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          name: jekyll-site
          path: _site

      - name: Select Xcode
        run: sudo xcode-select -s /Applications/Xcode_16.4.app

      - name: Generate DocC docs
        run: |
          SCHEME="HVCaptureSDK"

          # have derivedData outside of project dir to avoid SPM cache issue? https://forums.swift.org/t/xcode-and-swift-package-manager/44704/5
          TMP_BUILDIR="$HOME/doc-build"
          mkdir -p ${TMP_BUILDIR}
          DOCARCHIVE_DIR="tmp/docs"
          mkdir -p ${DOCARCHIVE_DIR}
          PAGE_DIR="tmp/site"
          mkdir -p ${PAGE_DIR}

          touch $HOME/.netrc
          echo "machine api.github.com" > $HOME/.netrc
          echo "login ${{ secrets.GITHUB_TOKEN }}" >> $HOME/.netrc
          echo "password ${{ secrets.GITHUB_TOKEN }}" >> $HOME/.netrc

          # compile the DocC archive(s)
          xcodebuild docbuild \
                     -scheme "${SCHEME}" \
                     -destination generic/platform=iOS \
                     -derivedDataPath "${TMP_BUILDIR}"
          # collect the generated docarchive(s)
          cp -R $(find ${TMP_BUILDIR} -type d -name "*.doccarchive") "${DOCARCHIVE_DIR}/."
          # NOTE: this command seems to wipe out the path specified by --output-path, so use a tmp dir that you don't mind getting deleted (i.e. don't use _site as the output directory directly)
          $(xcrun --find docc) process-archive transform-for-static-hosting "${DOCARCHIVE_DIR}/${SCHEME}.doccarchive" --hosting-base-path "hover-capture-ios" --output-path "${PAGE_DIR}"

          # Copy DocC Output to Jekyll Site
          mkdir -p _site/
          # get rid of the DocC index.html, since it's an empty page anyways and we don't want to overwrite the Jekyll one
          rm "${PAGE_DIR}"/index.html
          cp -R "${PAGE_DIR}"/* _site/.
          rm -rf "${TMP_BUILDIR}"

      - name: Fix GH-pages permissions
        run: |
          # from https://github.com/actions/upload-pages-artifact
          chmod -v -R +rX "_site/" | while read line; do
            echo "::warning title=Invalid file permissions automatically fixed::$line"
          done

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3

  # Deploy github pages job
  deploy:
    needs: build-docc

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    # Specify runner + deployment step
    runs-on: macos-15
    timeout-minutes: 5
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4