ci: check that API references do not cause Docusaurus build failures

[anakin87]

Related Issues

• Similarly to ci: check that API references do not cause Docusaurus build failures haystack-core-integrations#2829, we want to prevent that invalid API references land in Haystack, breaking Docusaurus build

Proposed Changes:

• add a "Check API reference changes" workflow: if python files or pydoc configs are changed
  • generates Markdown API references
  • runs docusaurus-mdx-checker, as suggested in Docusaurus docs: this does not build the website but just checks generated Markdown files.
    • if it fails, the informative build error is available on CI logs

How did you test it?

Temporarily added some changes:

• invalid docstring -> error: https://github.com/deepset-ai/haystack-experimental/actions/runs/21980075311/job/63500274087
• valid pydoc config change -> OK: https://github.com/deepset-ai/haystack-experimental/actions/runs/21980193348/job/63500663800

Notes for the reviewer

This is simpler than the approach used in deepset-ai/haystack-core-integrations#2829: we do not check docstrings checksums, etc. This means whenever python files or pydoc configs are changed, we generate all API references.

Since this repo generally has a small number of components and the whole workflow is fast and cheap (runs on Ubuntu slim), this simpler approach seems to be good enough.

Checklist

• I have read the contributors guidelines and the code of conduct
• I have updated the related issue with new insights and changes
• I added unit tests and updated the docstrings
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.
• I documented my code
• I ran pre-commit hooks and fixed any issue

[coveralls]

Pull Request Test Coverage Report for Build 21980075337

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 12 unchanged lines in 1 file lost coverage.
• Overall coverage remained the same at 57.682%

---

Files with Coverage Reduction	New Missed Lines	%
components/generators/chat/openai.py	12	46.67%

Totals
Change from base Build 21969631664:	0.0%
Covered Lines:	672
Relevant Lines:	1165

---

💛 - Coveralls

[julian-risch]

Looks good to me! Just wondering if we could use a more recent Python version. However, I understand tests use 3.10 too.

[julian-risch]

Any reason not to use a more recent version here? For example 3.13?

[anakin87]

In tests, it makes sense because it's the lower supported version.
Here not particularly -> I'll switch to 3.13