build_pr_documentation.yml

name: Build PR Documentation

env:
  DIFFUSERS_SLOW_IMPORT: yes

on:
  workflow_call:
    inputs:
      commit_sha:
        required: true
        type: string
      pr_number:
        required: true
        type: string
      package:
        required: true
        type: string
      package_name:
        type: string
        description: "Should be used when a package name differs from its repostory name"
      path_to_docs:
        type: string
      # supply --not_python_module for HF Course
      additional_args:
        type: string
      languages:
      # supply space-separated language codes
        type: string
      package_path:
        type: string
      install_rust:
        type: boolean
      install_libgl1:
        type: boolean
      # Command to execute before building the documentation
      pre_command:
        type: string
      repo_owner:
        type: string
        default: 'huggingface'
        description: "Owner of the repo to build documentation for. Defaults to 'huggingface'."
      version_tag_suffix:
        type: string
        default: "src/"
        description: "Suffix to add after the version tag (e.g. 1.3.0 or main) in the documentation links."
      convert_notebooks:
        type: boolean
        description: "Convert notebooks to markdown files before building docs."
      # Debug purposes only!
      doc_builder_revision:
        type: string
        default: "main"
        description: "Debug purposes only. Revision of `doc-builder` repo to use. Useful to test changes on `doc-builder`."
      fail_on_warning:
        type: boolean
        default: false
        description: "Fail doc build when runnable warnings are emitted. Requires `additional_args` to include `--emit-warning`."


jobs:
  build_pr_documentation:
    runs-on: ubuntu-22.04
    defaults:
      run:
        shell: bash
    env:
      UV_HTTP_TIMEOUT: 900 # max 15min to install deps (shouldn't take more than 5min)

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          repository: 'huggingface/doc-builder'
          path: doc-builder
          ref: ${{ inputs.doc_builder_revision }}

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          repository: '${{ inputs.repo_owner }}/${{ inputs.package }}'
          path: ${{ inputs.package }}

      - name: Checkout to the correct commit
        if: ${{ github.event_name == 'issue_comment' }}
        working-directory: ${{ inputs.package }}
        env:
          PR_NUMBER: ${{ inputs.pr_number }}
          REPO_OWNER: ${{ inputs.repo_owner }}
          PACKAGE: ${{ inputs.package }}
        run: |
         git fetch https://github.com/$REPO_OWNER/$PACKAGE.git refs/pull/$PR_NUMBER/merge:refs/remotes/pull/$PR_NUMBER/merge
         git checkout refs/remotes/pull/$PR_NUMBER/merge

      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
        with:
          node-version: '20'
          cache-dependency-path: "kit/package-lock.json"

      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3  # v8.3.0

      - name: Set env variables
        run: |
          if [ -z "${{ inputs.path_to_docs }}" ]
          then
            echo "doc_folder=${{ inputs.package }}/docs/source" >> $GITHUB_ENV
            echo "path_to_docs not provided, defaulting to ${{ inputs.package }}/docs/source"
          else
            echo "doc_folder=${{ inputs.path_to_docs }}" >> $GITHUB_ENV
          fi

          if [ -z "${{ inputs.package_name }}" ];
          then
            package_name=${{ inputs.package }}
          else
            package_name=${{ inputs.package_name }}
          fi

          if [ -z "${{ inputs.package_name }}" ];
          then
            echo "package_name=${{ inputs.package }}" >> $GITHUB_ENV
          else
            echo "package_name=${{ inputs.package_name }}" >> $GITHUB_ENV
          fi

      - name: Install libgl1
        if: inputs.install_libgl1
        run: sudo apt-get install -y libgl1

      - name: Install Rust
        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9  # master 2026-03-27
        if: inputs.install_rust
        with:
          toolchain: stable

      - name: Setup environment
        shell: bash
        run: |
          uv venv
          source .venv/bin/activate
          cd doc-builder
          git pull origin ${{ inputs.doc_builder_revision }}
          uv pip install .
          cd ..

          if [[ "${{ inputs.additional_args }}" == *"--not_python_module"* ]]
          then
            echo "Not a Python module; skipping package install."
          else
            package_dir="${{ inputs.package_path || inputs.package }}"
            # Light install when the package has a mock-deps registry entry: only its
            # real (light) doc-build deps are installed and the heavy ones are mocked
            # at build time. Falls back to a full [dev] install otherwise.
            if doc-builder light-install ${{ env.package_name }} --check
            then
              uv pip install "./$package_dir" --no-deps
              doc-builder light-install ${{ env.package_name }}
            else
              echo "Falling back to a full install."
              uv pip install "./$package_dir[dev]"
            fi
          fi

      - name: Run pre-command
        shell: bash
        env:
          PRE_COMMAND: ${{ inputs.pre_command }}
        run: |
          source .venv/bin/activate
          if [ ! -z "$PRE_COMMAND" ]
          then
            bash -c "$PRE_COMMAND"
          fi

      - name: Convert notebooks to markdown files
        if: inputs.convert_notebooks
        run: |
          source .venv/bin/activate
          branch=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}
          remaining_part=$(echo "${{ env.doc_folder }}" | perl -pe 's|^[^/]+||')
          remaining_part=${remaining_part%/}
          echo https://colab.research.google.com/github/${{ inputs.repo_owner }}/${{ inputs.package }}/blob/$branch$remaining_part

          doc-builder notebook-to-mdx ${{ env.doc_folder }} --open_notebook_prefix https://colab.research.google.com/github/${{ inputs.repo_owner }}/${{ inputs.package }}/blob/$branch$remaining_part

      - name: Make documentation
        env:
          NODE_OPTIONS: --max-old-space-size=6656
        shell: bash
        run: |
          source .venv/bin/activate
          echo "doc_folder has been set to ${{ env.doc_folder }}"
          cd doc-builder
          mkdir -p ../build_dir
          log_file="../build_dir/doc-build.log"
          : > "$log_file"
          set -o pipefail
          args="--build_dir ../build_dir --clean --version pr_${{ inputs.pr_number }} --html --html_page_cache hf://buckets/hf-doc-build/doc-build-cache ${{ inputs.additional_args }} --repo_owner ${{ inputs.repo_owner }} --repo_name ${{ inputs.package }} --version_tag_suffix=${{ inputs.version_tag_suffix }}"

          if [ -z "${{ inputs.languages }}" ];
          then
            echo "languages not provided, defaulting to English"
            doc-builder build ${{ env.package_name }} ../${{ env.doc_folder }} $args 2>&1 | tee -a "$log_file"
          else
            IFS=', ' read -r -a langs <<< "${{ inputs.languages }}"
            for lang in "${langs[@]}"
            do
                echo "Generating docs for language $lang"
                doc-builder build ${{ env.package_name }} ../${{ env.doc_folder }}/$lang $args --language $lang 2>&1 | tee -a "$log_file"
            done
          fi

          warnings_emitted=false
          if [[ "${{ inputs.additional_args }}" == *"--emit-warning"* ]] && grep -q "Bare assert found in runnable:" "$log_file"; then
            warnings_emitted=true
          fi
          echo "$warnings_emitted" > ../build_dir/warnings_emitted

          if [[ "$warnings_emitted" == "true" && "${{ inputs.fail_on_warning }}" == "true" ]]; then
            echo "::error::Doc build failed because warnings were emitted (fail_on_warning=true)."
            exit 1
          fi
          cd ..

      - name: Save commit_sha & pr_number
        run: |
          echo ${{ inputs.commit_sha }} > ./build_dir/commit_sha
          echo ${{ inputs.pr_number }} > ./build_dir/pr_number

      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
        with:
          name: doc-build-artifact
          path: build_dir/