ci: check that API references do not cause Docusaurus build failures #2
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: Check API reference changes | |
| on: | |
| pull_request: | |
| paths: | |
| - "haystack_experimental/**/*.py" | |
| - "pydoc/*.yml" | |
| jobs: | |
| test-api-reference-build: | |
| runs-on: ubuntu-slim | |
| steps: | |
| - uses: actions/checkout@v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.10" | |
| - name: Detect changes in API reference | |
| id: changed | |
| shell: python | |
| run: | | |
| import os | |
| import subprocess | |
| import sys | |
| from pathlib import Path | |
| sys.path.insert(0, ".github/utils") | |
| from docstrings_checksum import docstrings_checksum | |
| def git(*args): | |
| result = subprocess.run(["git", *args], capture_output=True, text=True) | |
| return result.stdout.strip(), result.returncode | |
| runner_temp = os.environ["RUNNER_TEMP"] | |
| base_sha, _ = git("rev-parse", "HEAD^1") | |
| # Check if pydoc config changed | |
| _, exit_code = git("diff", "--quiet", f"{base_sha}...HEAD", "--", "pydoc/") | |
| changed_api_ref = (exit_code != 0) | |
| if not changed_api_ref: | |
| # 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 | |
| # Check if docstrings changed | |
| pr_docstrings_checksum = docstrings_checksum(Path(".").glob("haystack_experimental/**/*.py")) | |
| base_docstrings_checksum = "" | |
| if has_worktree: | |
| base_docstrings_checksum = docstrings_checksum(Path(base_worktree).glob("haystack_experimental/**/*.py")) | |
| if base_docstrings_checksum != pr_docstrings_checksum: | |
| changed_api_ref = True | |
| print(f"API reference changes: {changed_api_ref}") | |
| with open(os.environ["GITHUB_OUTPUT"], "a") as f: | |
| f.write(f"changed_api_ref={changed_api_ref}\n") | |
| - name: Install Hatch | |
| if: steps.changed.outputs.changed_api_ref == 'true' | |
| run: pip install --upgrade hatch | |
| - name: Generate API references | |
| if: steps.changed.outputs.changed_api_ref == 'true' | |
| run: hatch run docs | |
| - name: Set up Node.js | |
| if: steps.changed.outputs.changed_api_ref == 'true' | |
| uses: actions/setup-node@v6 | |
| with: | |
| node-version: "22" | |
| - name: Run Docusaurus md/mdx checker | |
| if: steps.changed.outputs.changed_api_ref == 'true' | |
| working-directory: pydoc/temp | |
| run: | | |
| npx docusaurus-mdx-checker -v || { | |
| echo "" | |
| echo "For common MDX problems, see https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#common-mdx-problems" | |
| exit 1 | |
| } |