diff --git a/.github/workflows/api_doc_build.yml b/.github/workflows/api_doc_build.yml new file mode 100644 index 00000000000..a08953fd7b6 --- /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 "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"