style: docs snippets formatting

[kacperlukawski]

Related Issues

• implements Pre-commit hook for code snippets formatting #10535

Proposed Changes:

A new pre-commit hook that automatically formats code snippets in the documentation so we use consistent formatting. It uses the same settings like the entire project, but that might be a topic to discuss, since shorter lines might be better for the website.

How did you test it?

Manually tested with pre-commit.

Notes for the reviewer

I specifically launched it on one page of the documentation, to not clutter the PR. If we want to merge it, we need to rerun on all the documentation pages. I implemented it as a separate script, as I couldn't find any popular tool that would work with ruff, and not black.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have 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: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	Feb 12, 2026 0:51am

[anakin87]

I investigated a bit but basically came to the same conclusions as you: no existing tools for ruff + docstring; 3 steps are needed.

I'd run this pre-commit hook for all docs in this PR, so that we can also see if it's robust and behaves as expected.

[kacperlukawski]

@anakin87 That affected more than 2k files, so I decided to open a separate PR targetting this branch: #10554

Preview: https://haystack-docs-git-docs-snippets-formatting-attempt-deepset-ai.vercel.app/docs/

I already noticed some of the code snippets are skipped, so I'm going to investigate that. Example: https://haystack-docs-git-docs-snippets-formatting-attempt-deepset-ai.vercel.app/docs/secret-management#custom-component-example (uses 2 spaces for indent).

Edit: the section above actually uses mixed indentation (spaces and tabs), so ruff silently fails on it

[anakin87]

Good work!

I also ran the hook locally and works as expected.

(BTW, I use prek)

[anakin87]

Blocking to avoid conflicts with #10574 which is part of the release process.

After #10574 is merged (as soon as possible), we also need to rebase this PR.

[anakin87]

Merged the PR, please fix conflicts, and sorry. Basically, docs-website/versioned_docs/version-2.24-unstable no longer exists: has been promoted to docs-website/versioned_docs/version-2.24.

[anakin87]

Thank you!