1# Build the API reference documentation for v0.3 branch.2#3# Manual trigger only.4#5# Built HTML pushed to langchain-ai/langchain-api-docs-html.6#7# Looks for langchain-ai org repos in packages.yml and checks them out.8# Calls prep_api_docs_build.py.910name: "📚 API Docs (v0.3)"11run-name: "Build & Deploy API Reference (v0.3)"1213on:14  workflow_dispatch:1516permissions:17  contents: read1819env:20  PYTHON_VERSION: "3.11"2122jobs:23  build:24    if: github.repository == 'langchain-ai/langchain' || github.event_name != 'schedule'25    runs-on: ubuntu-latest26    permissions:27      contents: read28    steps:29      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v630        with:31          ref: v0.332          path: langchain3334      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v635        with:36          repository: langchain-ai/langchain-api-docs-html37          path: langchain-api-docs-html38          token: ${{ secrets.TOKEN_GITHUB_API_DOCS_HTML }}3940      - name: "📋 Extract Repository List with yq"41        id: get-unsorted-repos42        uses: mikefarah/yq@8f3291d3165497b360b8ffee3c887624bb6fa1cf # master43        with:44          cmd: |45            # Extract repos from packages.yml that are in the langchain-ai org46            # (excluding 'langchain' itself)47            yq '48              .packages[]49              | select(50                  (51                    (.repo | test("^langchain-ai/"))52                    and53                    (.repo != "langchain-ai/langchain")54                  )55                  or56                  (.include_in_api_ref // false)57                )58              | .repo59            ' langchain/libs/packages.yml6061      - name: "📋 Parse YAML & Checkout Repositories"62        env:63          REPOS_UNSORTED: ${{ steps.get-unsorted-repos.outputs.result }}64          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}65        run: |66          # Get unique repositories67          REPOS=$(echo "$REPOS_UNSORTED" | sort -u)68          # Checkout each unique repository69          for repo in $REPOS; do70            # Validate repository format (allow any org with proper format)71            if [[ ! "$repo" =~ ^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$ ]]; then72              echo "Error: Invalid repository format: $repo"73              exit 174            fi7576            REPO_NAME=$(echo $repo | cut -d'/' -f2)7778            # Additional validation for repo name79            if [[ ! "$REPO_NAME" =~ ^[a-zA-Z0-9_.-]+$ ]]; then80              echo "Error: Invalid repository name: $REPO_NAME"81              exit 182            fi83            echo "Checking out $repo to $REPO_NAME"8485            # Special handling for langchain-tavily: checkout by commit hash86            if [[ "$REPO_NAME" == "langchain-tavily" ]]; then87              git clone https://github.com/$repo.git $REPO_NAME88              cd $REPO_NAME89              git checkout f3515654724a9e87bdfe2c2f509d6cdde646e56390              cd ..91            else92              git clone --depth 1 --branch v0.3 https://github.com/$repo.git $REPO_NAME93            fi94          done9596      - name: "🐍 Setup Python ${{ env.PYTHON_VERSION }}"97        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v698        id: setup-python99        with:100          python-version: ${{ env.PYTHON_VERSION }}101102      - name: "📦 Install Initial Python Dependencies using uv"103        working-directory: langchain104        run: |105          python -m pip install -U uv106          python -m uv pip install --upgrade --no-cache-dir pip setuptools pyyaml107108      - name: "📦 Organize Library Directories"109        # Places cloned partner packages into libs/partners structure110        run: python langchain/.github/scripts/prep_api_docs_build.py111112      - name: "🧹 Clear Prior Build"113        run:114          # Remove artifacts from prior docs build115          rm -rf langchain-api-docs-html/api_reference_build/html116117      - name: "📦 Install Documentation Dependencies using uv"118        working-directory: langchain119        run: |120          # Install all partner packages in editable mode with overrides121          python -m uv pip install $(ls ./libs/partners | grep -v azure-ai | xargs -I {} echo "./libs/partners/{}") --overrides ./docs/vercel_overrides.txt --prerelease=allow122123          # Install langchain-azure-ai with tools extra124          python -m uv pip install "./libs/partners/azure-ai[tools]" --overrides ./docs/vercel_overrides.txt --prerelease=allow125126          # Install core langchain and other main packages127          python -m uv pip install libs/core libs/langchain libs/text-splitters libs/community libs/experimental libs/standard-tests128129          # Install Sphinx and related packages for building docs130          python -m uv pip install -r docs/api_reference/requirements.txt131132      - name: "🔧 Configure Git Settings"133        working-directory: langchain134        run: |135          git config --local user.email "actions@github.com"136          git config --local user.name "Github Actions"137138      - name: "📚 Build API Documentation"139        working-directory: langchain140        run: |141          # Generate the API reference RST files142          python docs/api_reference/create_api_rst.py143144          # Build the HTML documentation using Sphinx145          # -T: show full traceback on exception146          # -E: don't use cached environment (force rebuild, ignore cached doctrees)147          # -b html: build HTML docs (vs PDS, etc.)148          # -d: path for the cached environment (parsed document trees / doctrees)149          #     - Separate from output dir for faster incremental builds150          # -c: path to conf.py151          # -j auto: parallel build using all available CPU cores152          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 auto153154          # Post-process the generated HTML155          python docs/api_reference/scripts/custom_formatter.py ../langchain-api-docs-html/api_reference_build/html156157          # Default index page is blank so we copy in the actual home page.158          cp ../langchain-api-docs-html/api_reference_build/html/{reference,index}.html159160          # Removes Sphinx's intermediate build artifacts after the build is complete.161          rm -rf ../langchain-api-docs-html/_build/162163      # Commit and push changes to langchain-api-docs-html repo164      - uses: EndBug/add-and-commit@290ea2c423ad77ca9c62ae0f5b224379612c0321 # v10.0.0165        with:166          cwd: langchain-api-docs-html167          message: "Update API docs build from v0.3 branch"