ci: check that API references do not cause Docusaurus build failures #4
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-latest | |
| outputs: | |
| integrations: ${{ steps.changed.outputs.integrations }} | |
| steps: | |
| - uses: actions/checkout@v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Extract changed integrations | |
| id: changed | |
| run: | | |
| CHANGED=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...HEAD \ | |
| -- 'integrations/**/*.py' 'integrations/**/config_docusaurus.yml' \ | |
| | cut -d/ -f2 | sort -u | jq -Rc . | jq -sc .) | |
| echo "integrations=$CHANGED" >> "$GITHUB_OUTPUT" | |
| generate-docs: | |
| 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 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python 3.13 | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.13" | |
| - name: Check for Pydoc config changes | |
| id: config | |
| run: | | |
| if git diff --name-only ${{ github.event.pull_request.base.sha }}...HEAD -- "integrations/${{ matrix.integration }}/pydoc/config_docusaurus.yml" | grep -q .; then | |
| echo "changed=true" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "changed=false" >> "$GITHUB_OUTPUT" | |
| fi | |
| - name: Check for docstring changes | |
| if: steps.config.outputs.changed != 'true' | |
| id: docstrings | |
| run: | | |
| # Compute docstring checksum for the PR version | |
| PR_DOCSTRINGS_CHECKSUM=$(python .github/utils/docstrings_checksum.py --root . --integration ${{ matrix.integration }}) | |
| # Create a temporary worktree at the base SHA to compute the base checksum | |
| if git worktree add "${{ runner.temp }}/base" ${{ github.event.pull_request.base.sha }} 2>/dev/null; then | |
| BASE_DOCSTRINGS_CHECKSUM=$(python .github/utils/docstrings_checksum.py --root "${{ runner.temp }}/base" --integration ${{ matrix.integration }}) | |
| git worktree remove "${{ runner.temp }}/base" | |
| else | |
| # Integration doesn't exist on the base branch (new integration) | |
| BASE_DOCSTRINGS_CHECKSUM="" | |
| fi | |
| echo "changed=$([[ "$BASE_DOCSTRINGS_CHECKSUM" != "$PR_DOCSTRINGS_CHECKSUM" ]] && echo true || echo false)" >> "$GITHUB_OUTPUT" | |
| - name: Install Hatch | |
| if: steps.config.outputs.changed == 'true' || steps.docstrings.outputs.changed == 'true' | |
| run: pip install --upgrade hatch | |
| - name: Generate API reference | |
| if: steps.config.outputs.changed == 'true' || steps.docstrings.outputs.changed == 'true' | |
| working-directory: integrations/${{ matrix.integration }} | |
| run: | | |
| hatch run docs | |
| # save the generated API reference content to a variable | |
| INTEGRATION_API_REFERENCE=$(cat ${{ matrix.integration }}.md) | |
| echo "INTEGRATION_API_REFERENCE=$INTEGRATION_API_REFERENCE" >> "$GITHUB_OUTPUT" | |
| - name: Checkout Haystack repo | |
| uses: actions/checkout@v6 | |
| with: | |
| repository: deepset-ai/haystack | |
| ref: main | |
| - name: Sync API reference | |
| shell: python | |
| env: | |
| INTEGRATION_API_REFERENCE_FILENAME: ${{ matrix.integration }}.md | |
| run: | | |
| import os | |
| import shutil | |
| integration_api_reference = os.environ['INTEGRATION_API_REFERENCE'] | |
| integration_api_reference_filename = os.environ['INTEGRATION_API_REFERENCE_FILENAME'] | |
| with open(integration_api_reference_filename, 'w') as f: | |
| f.write(integration_api_reference) | |
| # Copy to main API reference | |
| shutil.copy(integration_api_reference, "docs-website/reference/integrations-api/") | |
| # Copy to versioned API reference | |
| for version_dir in os.scandir("docs-website/reference_versioned_docs"): | |
| if version_dir.is_dir(): | |
| # example: docs-website/reference_versioned_docs/version-2.17/integrations-api | |
| integrations_api_ref_dir = os.path.join(version_dir.path, "integrations-api") | |
| shutil.copy(integration_api_reference, integrations_api_ref_dir) | |
| os.remove(integration_api_reference_filename) | |
| - name: Print git status on docs | |
| working-directory: docs-website | |
| run: git status |