doc-build.yml

name: Build documentation

on:
  pull_request:
  push:
    branches:
      - main
      - release/*
    tags:
      - v[0-9]+.[0-9]+.[0-9]+
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *'

jobs:
  build:
    uses: pytorch/test-infra/.github/workflows/linux_job.yml@main
    strategy:
      matrix:
        include:
          - build-tool: buck2
    with:
      job-name: Build doc
      runner: linux.2xlarge
      docker-image: executorch-ubuntu-22.04-clang12
      submodules: 'true'
      repository: pytorch/executorch
      upload-artifact: docs
      script: |
        # The generic Linux job chooses to use base env, not the one setup by the image
        CONDA_ENV=$(conda env list --json | jq -r ".envs | .[-1]")
        conda activate "${CONDA_ENV}"

        BUILD_TOOL=${{ matrix.build-tool }}
        # Setup dependencies as there is no Docker support
        PYTHON_EXECUTABLE=python bash .ci/scripts/setup-linux.sh "${BUILD_TOOL}"

        if [[(${GITHUB_EVENT_NAME} = 'pull_request' && (${GITHUB_BASE_REF} = 'release'*)) || (${GITHUB_REF} = 'refs/heads/release'*) ]]; then
          export CHANNEL=test
        else
          export CHANNEL=nightly
        fi

        # Get the version of ExecuTorch from REF_NAME and save as ET_VERSION_DOCS
        # ET_VERSION_DOCS will be pulled during the doc build to add to the version dropdown
        # on the website. See docs/source/conf.py for details

        REF_TYPE=${{ github.ref_type }}
        REF_NAME=${{ github.ref_name }}

        echo "$REF_TYPE"
        echo "$REF_NAME"

        ET_VERSION_DOCS="${REF_NAME}"
        echo "$ET_VERSION_DOCS"

        set -eux

        # clean up the ${RUNNER_DOCS_DIR} if exists:
        rm -rf "${RUNNER_DOCS_DIR}"/*
        # clean up the ${RUNNER_ARTIFACT_DIR} if exists:
        rm -rf "${RUNNER_ARTIFACT_DIR}"/*

        # Build docset:
        cd docs
        doxygen source/Doxyfile
        make html
        cd ..

        cp -rf docs/_build/html/* "${RUNNER_DOCS_DIR}"

        mv docs/_build/html "${RUNNER_ARTIFACT_DIR}"

        ls -R "${RUNNER_ARTIFACT_DIR}"/*/*.html

# Enable preview later. Previews are available publicly
#
# upload-preview:
#    if: github.repository == 'pytorch/executorch' && github.event_name == 'push' &&
#        (github.ref_type == 'branch' && github.ref_name == 'main')
#    uses: pytorch/test-infra/.github/workflows/linux_job.yml@main

  upload-gh-pages:
    needs: build
    if: github.repository == 'pytorch/executorch' && github.event_name == 'push' &&
        ((github.ref_type == 'branch' && github.ref_name == 'main') || github.ref_type == 'tag')
    permissions:
      contents: write
    uses: pytorch/test-infra/.github/workflows/linux_job.yml@main
    with:
      repository: pytorch/executorch
      download-artifact: docs
      ref: gh-pages
      script: |
        set -euo pipefail

        REF_TYPE=${{ github.ref_type }}
        REF_NAME=${{ github.ref_name }}

        # If building for a release tag, branch, set the branch/tag name
        # as the target folder in the gh-pages branch. The artifacts created
        # during the build will be copied over to the target dir in the
        # gh-pages branch.
        if [[ "${REF_TYPE}" == branch ]]; then
          TARGET_FOLDER="${REF_NAME}"
        elif [[ "${REF_TYPE}" == tag ]]; then
          # Strip the leading "v" as well as the trailing patch version and "-rc" suffix.
          # For example: 'v0.1.2' -> '0.1' and 'v0.1.2-rc1' -> 0.1.
          TARGET_FOLDER=$(echo "${REF_NAME}" | sed 's/^v//i; s/-rc[0-9]*$//; s/\.[0-9]*$//')
        else
          echo "ERROR: Invalid REF_TYPE: ${REF_TYPE}. Expected 'branch' or 'tag'."
          exit 1
        fi
        echo "Target Folder: ${TARGET_FOLDER}"

        mkdir -p "${TARGET_FOLDER}"
        # Clean up target folder if exists and copy html output to the
        # Target folder
        rm -rf "${TARGET_FOLDER}"/*
        mv "${RUNNER_ARTIFACT_DIR}"/html/* "${TARGET_FOLDER}"
        git add "${TARGET_FOLDER}" || true

        # If it's main branch, add noindex tag to all .html files to exclude from Google Search indexing.
        if [[ "${REF_NAME}" == 'main' ]]; then
          find "${TARGET_FOLDER}" -type f -name "*.html" -exec sed -i '/<head>/a <meta name="robots" content="noindex">' {} \;
          git add "${TARGET_FOLDER}"/**/*.html || true
        fi

        git config user.name 'pytorchbot'
        git config user.email 'soumith+bot@pytorch.org'
        git commit -m "Auto-generating sphinx docs" || true
        git push -f