_docs.yml

name: build docs

on:
  workflow_call:
    inputs:
      build-environment:
        required: true
        type: string
        description: Top-level label for what's being built/tested.
      docker-image:
        required: true
        type: string
        description: Docker image to run in.
      push:
        required: false
        type: boolean
        default: false
        description: If set, push the docs to the docs website.
      run-doxygen:
        required: false
        type: boolean
        default: false
        description: If set, will enable C++ API doc generation using doxygen / breathe / exhale.
      sync-tag:
        required: false
        type: string
        default: ""
        description: |
          If this is set, our linter will use this to make sure that every other
          job with the same `sync-tag` is identical.
      s3-bucket:
        description: S3 bucket to download artifact
        required: false
        type: string
        default: "gha-artifacts"
      aws-role-to-assume:
        description: role to assume for downloading artifacts
        required: false
        type: string
        default: ""
      upload-aws-role-to-assume:
        description: role to assume for downloading artifacts
        required: false
        type: string
        default: ""
      runner_prefix:
        description: prefix for runner label
        type: string
        default: ""
      python-version:
        required: false
        type: string
        default: ""
        description: Python version to use for the OSDC build.
      compiler:
        required: false
        type: string
        default: ""
        description: Compiler to use for the OSDC build.
      cuda-version:
        required: false
        type: string
        default: ""
        description: CUDA version to use for the OSDC build.
    secrets:
      GH_PYTORCHBOT_TOKEN:
        required: false
        description: Permissions for pushing to the docs site.

jobs:
  build-docs:
    if: github.repository_owner == 'pytorch'
    permissions:
      id-token: write
      contents: read
      actions: read
    runs-on: ${{ matrix.runner }}
    environment: ${{ (github.ref == 'refs/heads/main' || startsWith(github.event.ref, 'refs/tags/v')) && 'pytorchbot-env' || '' }}
    container:
      image: ${{ inputs.docker-image }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - docs_type: cpp
            runner: ${{ inputs.runner_prefix }}l-x86iavx512-48-384
            timeout-minutes: 360
          - docs_type: python
            runner: ${{ inputs.runner_prefix }}l-x86iavx512-16-128
            timeout-minutes: 60
    name: build-docs-${{ matrix.docs_type }}-${{ inputs.push }}
    steps:
      - name: Setup Linux
        id: setup-linux
        uses: pytorch/pytorch/.github/actions/setup-linux@main
        with:
          use-arc: true
          python-version: ${{ inputs.python-version }}
          compiler: ${{ inputs.compiler }}
          cuda-version: ${{ inputs.cuda-version }}
          submodules: false
          # Docs build runs `git log --follow` per page for "Created/Updated"
          # dates; a treeless clone triggers lazy fetches and makes the build
          # hang. Use a full checkout for this job.
          checkout-mode: normal
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Configure AWS credentials
        id: aws-creds
        continue-on-error: true
        uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7
        with:
          role-to-assume: arn:aws:iam::308535385114:role/arc
          aws-region: us-east-1
          role-duration-seconds: 18000

      - name: Download build artifacts
        uses: pytorch/pytorch/.github/actions/download-build-artifacts@main
        with:
          name: ${{ inputs.build-environment }}
          s3-bucket: ${{ inputs.s3-bucket }}
          use-gha: ${{ steps.aws-creds.outcome != 'success' }}

      - name: Generate netrc (only for docs-push)
        if: inputs.push
        env:
          GITHUB_PYTORCHBOT_TOKEN: ${{ secrets.GH_PYTORCHBOT_TOKEN }}
        run: |
          rm -rf "${HOME}/.netrc"
          echo "machine github.com" > "${HOME}/.netrc"
          echo "login pytorchbot" >> "${HOME}/.netrc"
          echo "password ${GITHUB_PYTORCHBOT_TOKEN}" >> "${HOME}/.netrc"

      - name: Build ${{ matrix.docs_type }} docs
        timeout-minutes: ${{ matrix.timeout-minutes }}
        id: build-docs
        env:
          WITH_PUSH: ${{ inputs.push }}
          DOCS_TYPE: ${{ matrix.docs_type }}
          RUN_DOXYGEN: ${{ inputs.run-doxygen }}
          BUILD_ENVIRONMENT: ${{ inputs.build-environment }}
          SHA1: ${{ github.sha }}
        shell: bash
        run: |
          set -ex
          if [[ "${GITHUB_REF}" =~ ^refs/tags/v([0-9]+\.[0-9]+)\.* ]]; then
            target="${BASH_REMATCH[1]}"
          else
            target="main"
          fi
          export DOCS_VERSION="${target}"
          pip install $(echo dist/*.whl)[opt-einsum]
          ./.ci/pytorch/${DOCS_TYPE}_doc_push_script.sh

      # The OSDC pod cannot upload to s3://doc-previews directly: fork PRs cannot
      # authenticate via OIDC, and we don't want to grant the pod's IAM role
      # write access. Stage the built docs as a GHA artifact and let the
      # upload-docs-preview workflow (running via workflow_run in the base repo
      # context) do the actual S3 upload.
      - name: Stage docs preview artifact (PR)
        if: ${{ github.event_name == 'pull_request' && steps.build-docs.outcome == 'success' }}
        shell: bash
        run: |
          set -ex
          if [ "${{ matrix.docs_type }}" = "python" ]; then
            src_dir="pytorch_docs/main"
          else
            src_dir="cppdocs"
          fi
          mkdir -p docs-preview-staging
          cp -r "${src_dir}" docs-preview-staging/content
          cat > docs-preview-staging/pr-metadata.txt <<EOF
          PR_NUMBER=${{ github.event.pull_request.number }}
          DOCS_TYPE=${{ matrix.docs_type }}
          SHA=${{ github.sha }}
          EOF

      - name: Upload docs preview artifact (PR)
        if: ${{ github.event_name == 'pull_request' && steps.build-docs.outcome == 'success' }}
        uses: actions/upload-artifact@v4
        with:
          name: docs-preview-osdc-${{ matrix.docs_type }}
          path: docs-preview-staging
          retention-days: 14
          if-no-files-found: error

      - name: Post C++ Docs Coverage Comment
        # Skip on fork PRs since the GITHUB_TOKEN is read-only there.
        if: ${{ github.event_name == 'pull_request' && matrix.docs_type == 'cpp' && steps.build-docs.outcome == 'success' && github.event.pull_request.head.repo.full_name == github.repository }}
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_NUM="${{ github.event.pull_request.number }}"
          MARKER="<!-- cpp-docs-coverage -->"

          # Only post if the PR touches docs/cpp
          if ! gh pr diff "$PR_NUM" --name-only | grep -q '^docs/cpp/'; then
            echo "No changes to docs/cpp/, skipping coverage comment."
            exit 0
          fi

          # Skip if we already posted
          if gh pr view "$PR_NUM" --json comments --jq '.comments[].body' | grep -q "$MARKER"; then
            echo "Coverage comment already posted, skipping."
            exit 0
          fi

          body="${MARKER}
          ## C++ Docs

          - [Doc Preview](https://docs-preview.pytorch.org/pytorch/pytorch/${PR_NUM}/cppdocs/index.html)
          - [API Coverage Report](https://docs-preview.pytorch.org/pytorch/pytorch/${PR_NUM}/cppdocs/_coverage/cpp_coverage.txt)
          - [HTML Issues Report](https://docs-preview.pytorch.org/pytorch/pytorch/${PR_NUM}/cppdocs/_coverage/cpp_html_issues.txt)"

          if [ -f cppdocs/_coverage/index.html ]; then
            body="${body}
          - [Coverxygen Report (interactive)](https://docs-preview.pytorch.org/pytorch/pytorch/${PR_NUM}/cppdocs/_coverage/index.html)"
          fi

          gh pr comment "$PR_NUM" --body "$body"

      # The nightly C++ dry-run preview is intentionally not produced from the
      # OSDC path: the upload-docs-preview workflow_run uploader only handles
      # PR events. If nightly OSDC previews are needed, extend that uploader
      # to trigger on the corresponding workflow.

  memory-viz-tests:
    # Tests for torch memory visualizer
    # tag shangdiy for any issue with this test
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Run MemoryViz JS tests (nonretryable)
        run: node test/profiler/test_memory_viz.js