docs.yml

# This workflow builds the tensordict docs and deploys them to gh-pages.
name: Generate documentation
on:
  push:
    branches:
      - nightly
      - main
      - release/*
    tags:
      - v[0-9]+.[0-9]+.[0-9]
      - v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+
  pull_request:
  workflow_dispatch:
  workflow_call:

concurrency:
  # Documentation suggests ${{ github.head_ref }}, but that's only available on pull_request/pull_request_target triggers, so using ${{ github.ref }}.
  # On master, we want all builds to complete even if merging happens faster to make it easier to discover at which point something broke.
  group: docs-${{ github.ref == 'refs/heads/main' && format('ci-master-{0}', github.sha) || format('ci-{0}', github.ref) }}
  cancel-in-progress: true

jobs:
  build-docs:
    strategy:
      matrix:
        python_version: ["3.10"]
        cuda_arch_version: ["12.8"]
    uses: pytorch/test-infra/.github/workflows/linux_job_v2.yml@main
    permissions:
      id-token: write
      contents: read
    with:
      repository: pytorch/tensordict
      upload-artifact: docs
      runner: "linux.g5.4xlarge.nvidia.gpu"
      docker-image: "nvidia/cuda:12.8.0-devel-ubuntu22.04"
      timeout: 120
      script: |
        set -e
        set -v

        # Set up environment variables
        export PYTHON_VERSION=3.10
        export CU_VERSION="cpu"
        export TORCH_VERSION=nightly
        export ARCH=x86_64

        # Use existing setup script
        bash .github/unittest/linux/scripts/setup_env.sh

        # Install additional tools needed for docs build
        apt update && apt install -y unzip

        # Activate the conda environment
        eval "$(./conda/bin/conda shell.bash hook)"
        conda activate "./env"

        # Install PyTorch and torchvision (CPU version for docs)
        python -m pip install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cpu -U --quiet --root-user-action=ignore

        # Install tensordict runtime deps explicitly (except torch which is handled above),
        # then install tensordict without resolving dependencies to avoid any solver changing the
        # PyTorch build (stable vs nightly).
        python -m pip install -U packaging pyvers importlib_metadata --quiet --root-user-action=ignore

        # Set up versioning environment (conditional on release branch/tag)
        export GITHUB_REF_TYPE=${{ github.ref_type }}
        export GITHUB_REF_NAME=${{ github.ref_name }}
        source .github/scripts/version_script.sh

        # Install tensordict -- install as develop if not on a release branch
        if [[ ${{ github.ref_type }} == branch && ${{ github.ref_name }} == release/* ]] || [[ ${{ github.ref_type }} == tag ]]; then
          python -m pip install . --no-deps
        else
          python -m pip install -e . --no-deps
        fi

        # Install docs requirements
        export TD_GET_DEFAULTS_TO_NONE='1'
        python -m pip install -r docs/requirements.txt --quiet --root-user-action=ignore

        # Test tensordict installation
        mkdir _tmp
        cd _tmp
        PYOPENGL_PLATFORM=egl MUJOCO_GL=egl python -c "from tensordict import *"
        cd ..

        # Set sanitize version for releases
        if [[ ${{ github.event_name }} == push && (${{ github.ref_type }} == tag || (${{ github.ref_type }} == branch && ${{ github.ref_name }} == release/*)) ]]; then
          echo '::group::Enable version string sanitization'
          # This environment variable just has to exist and must not be empty. The actual value is arbitrary.
          # See docs/source/conf.py for details
          export TENSORDICT_SANITIZE_VERSION_STR_IN_DOCS=1
          echo '::endgroup::'
        fi

        # Build documentation
        cd ./docs
        make docs
        cd ..

        # Copy artifacts
        cp -r docs/build/html/* "${RUNNER_ARTIFACT_DIR}"
        echo $(ls "${RUNNER_ARTIFACT_DIR}")
        if [[ ${{ github.event_name == 'pull_request' }} ]]; then
          cp -r docs/build/html/* "${RUNNER_DOCS_DIR}"
        fi

  upload:
    needs: build-docs
    if: github.repository == 'pytorch/tensordict' && 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/tensordict
      download-artifact: docs
      ref: gh-pages
      test-infra-ref: main
      script: |
        set -euo pipefail

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

        if [[ "${REF_TYPE}" == branch ]]; then
          if [[ "${REF_NAME}" == main ]]; then
            TARGET_FOLDER="${REF_NAME}"
          # Bebug:
          # else
          #   TARGET_FOLDER="release-doc"
          fi
        elif [[ "${REF_TYPE}" == tag ]]; then
          case "${REF_NAME}" in
            *-rc*)
              echo "Aborting upload since this is an RC tag: ${REF_NAME}"
              exit 0
              ;;
            *)
              # Strip the leading "v" as well as the trailing patch version. For example:
              # 'v0.15.2' -> '0.15'
              TARGET_FOLDER=$(echo "${REF_NAME}" | sed 's/v\([0-9]\+\)\.\([0-9]\+\)\.[0-9]\+/\1.\2/')
              ;;
          esac
        fi

        echo "Target Folder: ${TARGET_FOLDER}"

        mkdir -p "${TARGET_FOLDER}"
        rm -rf "${TARGET_FOLDER}"/*

        echo $(ls "${RUNNER_ARTIFACT_DIR}")
        rsync -a "${RUNNER_ARTIFACT_DIR}"/ "${TARGET_FOLDER}"
        git add "${TARGET_FOLDER}" || true

        if [[ "${TARGET_FOLDER}" == "main" ]] ; then
          mkdir -p _static
          rm -rf _static/*
          cp -r "${TARGET_FOLDER}"/_static/* _static
          git add _static || true
        fi

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