langchain/.github/workflows/api_doc_build.yml

# Build the API reference documentation for v0.3 branch.
#
# Manual trigger only.
#
# Built HTML pushed to langchain-ai/langchain-api-docs-html.
#
# Looks for langchain-ai org repos in packages.yml and checks them out.
# Calls prep_api_docs_build.py.

name: "📚 API Docs (v0.3)"
run-name: "Build & Deploy API Reference (v0.3)"

on:
  workflow_dispatch:

env:
  PYTHON_VERSION: "3.11"

jobs:
  build:
    if: github.repository == 'langchain-ai/langchain' || github.event_name != 'schedule'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: v0.3
          path: langchain

      - uses: actions/checkout@v5
        with:
          repository: langchain-ai/langchain-api-docs-html
          path: langchain-api-docs-html
          token: ${{ secrets.TOKEN_GITHUB_API_DOCS_HTML }}

      - name: "📋 Extract Repository List with yq"
        id: get-unsorted-repos
        uses: mikefarah/yq@master
        with:
          cmd: |
            # Extract repos from packages.yml that are in the langchain-ai org
            # (excluding 'langchain' itself)
            yq '
              .packages[]
              | select(
                  (
                    (.repo | test("^langchain-ai/"))
                    and
                    (.repo != "langchain-ai/langchain")
                  )
                  or
                  (.include_in_api_ref // false)
                )
              | .repo
            ' langchain/libs/packages.yml

      - name: "📋 Parse YAML & Checkout Repositories"
        env:
          REPOS_UNSORTED: ${{ steps.get-unsorted-repos.outputs.result }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Get unique repositories
          REPOS=$(echo "$REPOS_UNSORTED" | sort -u)
          # Checkout each unique repository
          for repo in $REPOS; do
            # Validate repository format (allow any org with proper format)
            if [[ ! "$repo" =~ ^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$ ]]; then
              echo "Error: Invalid repository format: $repo"
              exit 1
            fi

            REPO_NAME=$(echo $repo | cut -d'/' -f2)

            # Additional validation for repo name
            if [[ ! "$REPO_NAME" =~ ^[a-zA-Z0-9_.-]+$ ]]; then
              echo "Error: Invalid repository name: $REPO_NAME"
              exit 1
            fi
            echo "Checking out $repo to $REPO_NAME"

            # Special handling for langchain-tavily: checkout by commit hash
            if [[ "$REPO_NAME" == "langchain-tavily" ]]; then
              git clone https://github.com/$repo.git $REPO_NAME
              cd $REPO_NAME
              git checkout f3515654724a9e87bdfe2c2f509d6cdde646e563
              cd ..
            else
              git clone --depth 1 --branch v0.3 https://github.com/$repo.git $REPO_NAME
            fi
          done

      - name: "🐍 Setup Python ${{ env.PYTHON_VERSION }}"
        uses: actions/setup-python@v6
        id: setup-python
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: "📦 Install Initial Python Dependencies using uv"
        working-directory: langchain
        run: |
          python -m pip install -U uv
          python -m uv pip install --upgrade --no-cache-dir pip setuptools pyyaml

      - name: "📦 Organize Library Directories"
        # Places cloned partner packages into libs/partners structure
        run: python langchain/.github/scripts/prep_api_docs_build.py

      - name: "🧹 Clear Prior Build"
        run:
          # Remove artifacts from prior docs build
          rm -rf langchain-api-docs-html/api_reference_build/html

      - name: "📦 Install Documentation Dependencies using uv"
        working-directory: langchain
        run: |
          # Install all partner packages in editable mode with overrides
          python -m uv pip install $(ls ./libs/partners | xargs -I {} echo "./libs/partners/{}") --overrides ./docs/vercel_overrides.txt

          # Install core langchain and other main packages
          python -m uv pip install libs/core libs/langchain libs/text-splitters libs/community libs/experimental libs/standard-tests

          # Install Sphinx and related packages for building docs
          python -m uv pip install -r docs/api_reference/requirements.txt

      - name: "🔧 Configure Git Settings"
        working-directory: langchain
        run: |
          git config --local user.email "actions@github.com"
          git config --local user.name "Github Actions"

      - name: "📚 Build API Documentation"
        working-directory: langchain
        run: |
          # Generate the API reference RST files
          python docs/api_reference/create_api_rst.py

          # Build the HTML documentation using Sphinx
          # -T: show full traceback on exception
          # -E: don't use cached environment (force rebuild, ignore cached doctrees)
          # -b html: build HTML docs (vs PDS, etc.)
          # -d: path for the cached environment (parsed document trees / doctrees)
          #     - Separate from output dir for faster incremental builds
          # -c: path to conf.py
          # -j auto: parallel build using all available CPU cores
          python -m sphinx -T -E -b html -d ../langchain-api-docs-html/_build/doctrees -c docs/api_reference docs/api_reference ../langchain-api-docs-html/api_reference_build/html -j auto

          # Post-process the generated HTML
          python docs/api_reference/scripts/custom_formatter.py ../langchain-api-docs-html/api_reference_build/html

          # Default index page is blank so we copy in the actual home page.
          cp ../langchain-api-docs-html/api_reference_build/html/{reference,index}.html

          # Removes Sphinx's intermediate build artifacts after the build is complete.
          rm -rf ../langchain-api-docs-html/_build/

      # Commit and push changes to langchain-api-docs-html repo
      - uses: EndBug/add-and-commit@v9
        with:
          cwd: langchain-api-docs-html
          message: "Update API docs build from v0.3 branch"