From be8d87fe0ebc69f96feae8cf9b76aabc1a0c275b Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Tue, 23 Sep 2025 13:38:37 -0400 Subject: [PATCH] refactor(docs): enhance script and workflow documentation for clarity --- .github/scripts/prep_api_docs_build.py | 20 +++++++++++------ .github/workflows/api_doc_build.yml | 30 ++++++++++++++++++++++---- 2 files changed, 40 insertions(+), 10 deletions(-) diff --git a/.github/scripts/prep_api_docs_build.py b/.github/scripts/prep_api_docs_build.py index 460a24d1fcf..b3df069dba8 100644 --- a/.github/scripts/prep_api_docs_build.py +++ b/.github/scripts/prep_api_docs_build.py @@ -1,5 +1,8 @@ #!/usr/bin/env python -"""Sync libraries from various repositories into this monorepo.""" +"""Sync libraries from various repositories into this monorepo. + +Moves cloned partner packages into libs/partners structure. +""" import os import shutil @@ -10,7 +13,7 @@ import yaml def load_packages_yaml() -> Dict[str, Any]: - """Load and parse the packages.yml file.""" + """Load and parse packages.yml.""" with open("langchain/libs/packages.yml", "r") as f: return yaml.safe_load(f) @@ -61,12 +64,15 @@ def move_libraries(packages: list) -> None: def main(): - """Main function to orchestrate the library sync process.""" + """Orchestrate the library sync process.""" try: # Load packages configuration package_yaml = load_packages_yaml() - # Clean target directories + # Clean/empty target directories in preparation for moving new ones + # + # Only for packages in the langchain-ai org or explicitly included via + # include_in_api_ref, excluding 'langchain' itself and 'langchain-ai21' clean_target_directories( [ p @@ -80,7 +86,9 @@ def main(): ] ) - # Move libraries to their new locations + # Move cloned libraries to their new locations, only for packages in the + # langchain-ai org or explicitly included via include_in_api_ref, + # excluding 'langchain' itself and 'langchain-ai21' move_libraries( [ p @@ -95,7 +103,7 @@ def main(): ] ) - # Delete ones without a pyproject.toml + # Delete partner packages without a pyproject.toml for partner in Path("langchain/libs/partners").iterdir(): if partner.is_dir() and not (partner / "pyproject.toml").exists(): print(f"Removing {partner} as it does not have a pyproject.toml") diff --git a/.github/workflows/api_doc_build.yml b/.github/workflows/api_doc_build.yml index f7c2c62792b..e14e40cf9f2 100644 --- a/.github/workflows/api_doc_build.yml +++ b/.github/workflows/api_doc_build.yml @@ -1,6 +1,11 @@ # Build the API reference documentation. # # Runs daily. Can also be triggered manually for immediate updates. +# +# 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' run-name: 'Build & Deploy API Reference' @@ -34,6 +39,8 @@ jobs: uses: mikefarah/yq@master with: cmd: | + # Extract repos from packages.yml that are in the langchain-ai org + # (excluding 'langchain' itself) yq ' .packages[] | select( @@ -80,24 +87,31 @@ jobs: with: python-version: ${{ env.PYTHON_VERSION }} - - name: '๐Ÿ“ฆ Install Initial Python Dependencies' + - 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: '๐Ÿงน Remove Old HTML Files' + - 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' + - 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' @@ -109,14 +123,22 @@ jobs: - 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 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/ - # https://github.com/marketplace/actions/add-commit + # Commit and push changes to langchain-api-docs-html repo - uses: EndBug/add-and-commit@v9 with: cwd: langchain-api-docs-html