ci: add workflow for manually building API ref for v0.3 (#33241)

.github/workflows/api_doc_build.yml

@@ -0,0 +1,152 @@
+# 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"
+            git clone --depth 1 https://github.com/$repo.git $REPO_NAME
+          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"