ci: check that API references do not cause Docusaurus build failures #15
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Core / Check API reference changes | |
| on: | |
| pull_request: | |
| paths: | |
| - "integrations/**/*.py" | |
| - "integrations/**/config_docusaurus.yml" | |
| jobs: | |
| detect-changes: | |
| runs-on: ubuntu-slim | |
| outputs: | |
| integrations: ${{ steps.changed.outputs.integrations }} | |
| steps: | |
| - uses: actions/checkout@v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.13" | |
| - name: Detect integrations with API reference changes | |
| id: changed | |
| shell: python | |
| env: | |
| BASE_SHA: ${{ github.event.pull_request.base.sha }} | |
| run: | | |
| import json | |
| import os | |
| import subprocess | |
| import sys | |
| from pathlib import Path | |
| sys.path.insert(0, ".github/utils") | |
| from docstrings_checksum import docstrings_checksum | |
| base_sha = os.environ["BASE_SHA"] | |
| runner_temp = os.environ["RUNNER_TEMP"] | |
| def git(*args): | |
| result = subprocess.run(["git", *args], capture_output=True, text=True) | |
| return result.stdout.strip(), result.returncode | |
| # Get all changed files | |
| diff_output, _ = git( | |
| "diff", "--name-only", f"{base_sha}...HEAD", "--", "integrations" | |
| ) | |
| changed_files = set(diff_output.splitlines()) | |
| # Extract integration names | |
| candidates = sorted({ | |
| Path(p).parts[1] | |
| for p in changed_files | |
| if p.startswith("integrations/") and len(Path(p).parts) > 1 | |
| }) | |
| # Create base worktree for docstring comparison | |
| base_worktree = os.path.join(runner_temp, "base") | |
| _, return_code = git("worktree", "add", base_worktree, base_sha) | |
| has_worktree = return_code == 0 | |
| changed_integrations = [] | |
| for integration in candidates: | |
| # If pydoc config changed, always include | |
| if f"integrations/{integration}/pydoc/config_docusaurus.yml" in changed_files: | |
| changed_integrations.append(integration) | |
| continue | |
| # Otherwise, check if docstrings changed | |
| pr_docstrings_checksum = docstrings_checksum(Path(".").glob(f"integrations/{integration}/**/*.py")) | |
| base_docstrings_checksum = "" | |
| if has_worktree: | |
| base_docstrings_checksum = docstrings_checksum(Path(base_worktree).glob(f"integrations/{integration}/**/*.py")) | |
| if base_docstrings_checksum != pr_docstrings_checksum: | |
| changed_integrations.append(integration) | |
| if has_worktree: | |
| git("worktree", "remove", base_worktree) | |
| print(f"Integrations with API reference changes: {json.dumps(changed_integrations)}") | |
| with open(os.environ["GITHUB_OUTPUT"], "a") as f: | |
| f.write(f"integrations={json.dumps(changed_integrations)}\n") | |
| test-api-reference-build: | |
| needs: detect-changes | |
| if: needs.detect-changes.outputs.integrations != '[]' | |
| runs-on: ubuntu-latest | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| integration: ${{ fromJson(needs.detect-changes.outputs.integrations) }} | |
| steps: | |
| - uses: actions/checkout@v6 | |
| - name: Set up Python 3.13 | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.13" | |
| - name: Install Hatch | |
| run: pip install --upgrade hatch | |
| - name: Generate API reference | |
| working-directory: integrations/${{ matrix.integration }} | |
| run: | | |
| hatch run docs | |
| # Save the generated file before the Haystack checkout overwrites the working tree | |
| cp ${{ matrix.integration }}.md "${{ runner.temp }}/${{ matrix.integration }}.md" | |
| # Also copy the Copy script to the temp directory | |
| cp ../../.github/utils/copy_file_to_api_reference.py "${{ runner.temp }}/copy_file_to_api_reference.py" | |
| - name: Checkout Haystack Docs Website | |
| uses: actions/checkout@v6 | |
| with: | |
| repository: deepset-ai/haystack | |
| ref: main | |
| sparse-checkout: docs-website | |
| - name: Copy file to API reference | |
| run: python ${{ runner.temp }}/copy_file_to_api_reference.py ${{ runner.temp }}/${{ matrix.integration }}.md | |
| - name: Install Node.js | |
| uses: actions/setup-node@v6 | |
| with: | |
| node-version: "22" | |
| - name: Build docs-website | |
| working-directory: docs-website | |
| run: | | |
| npm install | |
| npm run build |