build_main_documentation.yml

name: Build PR Documentation

env:
  DIFFUSERS_SLOW_IMPORT: yes

on:
  workflow_call:
    inputs:
      commit_sha:
        required: true
        type: string
      package:
        required: true
        type: string
        description: "Name of the GitHub repo."
      package_name:
        type: string
        description: "Name of the Python package if it differs from repo name."
      path_to_docs:
        type: string
      notebook_folder:
        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."
    secrets:
      hf_token:
        required: true
      token:
        required: false

jobs:
  build_main_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

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

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        if: inputs.notebook_folder != ''
        with:
          repository: 'huggingface/notebooks'
          path: notebooks
          token: ${{ secrets.token }}

      - 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
            echo "package_name=${{ inputs.package }}" >> $GITHUB_ENV
          else
            echo "package_name=${{ inputs.package_name }}" >> $GITHUB_ENV
          fi

      # Needed to upload zips to hf.co
      - name: Install zip
        run: sudo apt-get install -y zip

      - 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 main
          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: Setup git
        run: |
          git config --global user.name "Hugging Face Doc Builder"
          git config --global user.email docs@huggingface.co

      # The version list is read from the bucket we serve from, not from the legacy
      # dataset: a version advertised in _versions.yml with no matching folder in the
      # bucket makes hf.co/docs/<package> 404 on its default version.
      - name: Create build directory
        env:
          HF_TOKEN: ${{ secrets.hf_token }}
          PACKAGE_NAME: ${{ env.package_name }}
        run: |
          mkdir build_dir
          mkdir build_dir/$PACKAGE_NAME
          cd build_dir/$PACKAGE_NAME
          uvx --from huggingface_hub hf cp "hf://buckets/hf-doc-build/doc/$PACKAGE_NAME/_versions.yml" _versions.yml

      - name: Run pre-command
        shell: bash
        run: |
          source .venv/bin/activate
          if [ ! -z "${{ inputs.pre_command }}" ]
          then
            bash -c "${{ inputs.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
        shell: bash
        env:
          NODE_OPTIONS: --max-old-space-size=6656
          # needed for --html_page_cache_write (trusted main builds only)
          HF_TOKEN: ${{ secrets.hf_token }}
        run: |
          source .venv/bin/activate
          echo "doc_folder has been set to ${{ env.doc_folder }}"
          cd doc-builder
          args="--build_dir ../build_dir --clean --html --html_page_cache hf://buckets/hf-doc-build/doc-build-cache --html_page_cache_write ${{ inputs.additional_args }} --repo_owner ${{ inputs.repo_owner }} --repo_name ${{ inputs.package }} --version_tag_suffix=${{ inputs.version_tag_suffix }}"

          if [ ! -z "${{ inputs.notebook_folder }}" ];
          then
            args="$args --notebook_dir ../notebook_dir"
          fi

          if [ -z "${{ inputs.languages }}" ];
          then
            echo "languages not provided, defaulting to English"
            doc-builder build ${{ env.package_name }} ../${{ env.doc_folder }} $args
          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
            done
          fi

          cd ..

      - name: Sync to bucket
        env:
          HF_TOKEN: ${{ secrets.hf_token }}
          PACKAGE_NAME: ${{ env.package_name }}
        run: |
          cd build_dir
          uvx --from huggingface_hub hf sync "./$PACKAGE_NAME" "hf://buckets/hf-doc-build/doc/$PACKAGE_NAME"
          cd ..

      - name: Push to dataset (legacy, kept for rollback safety)
        run: |
          source .venv/bin/activate
          cd build_dir
          doc-builder push ${{ env.package_name }} --doc_build_repo_id "hf-doc-build/doc-build" --token "${{ secrets.hf_token }}" --commit_msg "Updated with commit ${{ inputs.commit_sha }} See: https://github.com/${{ inputs.repo_owner }}/${{ inputs.package }}/commit/${{ inputs.commit_sha }}" --n_retries 5 --upload_version_yml
          cd ..

      - name: Commit notebooks
        run: |
          if [ -d "notebook_dir" ]
          then
            cd notebooks
            git pull
            cp -r ../notebook_dir/. ${{ inputs.notebook_folder }}
            git status
            if [[ `git status --porcelain` ]]; then
              git add ${{ inputs.notebook_folder }}
              git commit -m "Updated ${{ inputs.package }} doc notebooks with commit ${{ inputs.commit_sha }} \n\nSee: https://github.com/huggingface/${{ inputs.package }}/commit/${{ inputs.commit_sha }}"
              git push origin main ||
              (echo "Failed on the first try, rebasing and pushing again" && git pull --rebase && git push origin main) ||
              (echo "Failed on the second try, rebasing and pushing again" && git pull --rebase && git push origin main)
            else
              echo "No diff in the notebooks."
            fi
            cd ..
          else
            echo "Notebooks creation was not enabled."
          fi
        shell: bash