Skip to content

The agent engineering platform.

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

Mason Daughertye2e0327c90a4
diff --git a/.github/workflows/api_doc_build.yml b/.github/workflows/api_doc_build.yml
new file mode 100644
index 0000000000..a08953fd7b
--- /dev/null
+++ b/.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 "[email protected]"
+ 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"