docs: expand PaddleOCR advanced usage guide

[jimmyzhuu]

Related Issues

Closes #11017

Summary

This PR expands the PaddleOCRVLDocumentConverter documentation so it is more useful for people working with real OCR ingestion pipelines.

It adds:

• clearer guidance on when PaddleOCR is a good fit
• grouped guidance for the most useful advanced parameters
• scenario-based recommendations for common document types
• a more realistic advanced example for structure-heavy PDFs
• a short note on how raw_paddleocr_responses can help during tuning

What changed

• Added a short explanation of why raw_paddleocr_responses is useful during tuning.
• Added a When to use it section.
• Added a Useful configuration areas section that groups high-value parameters by purpose.
• Added a Typical scenarios section with practical configuration suggestions.
• Added an advanced example for layout-heavy PDFs using options like:
  • use_doc_orientation_classify
  • use_doc_unwarping
  • use_layout_detection
  • use_ocr_for_image_block
  • merge_tables
  • restructure_pages
  • prettify_markdown
• Synced the same docs update to version-2.27-unstable.
• Added a release note.

Checklist

• I have read the contributors guidelines.
• I have updated the related issue with new insights and changes.
• I have added tests or explained why they are not needed.
• I have added release notes.
• I have updated the documentation accordingly.

Notes for reviewers

This is a docs-only change.
No runtime behavior was changed.

Validation run locally:

• pre-commit on the changed docs files and release note
• npm run build in docs-website

[vercel]

@jimmyzhuu is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[anakin87]

@jimmyzhuu just an info: 2.27 has been just released so you should do these changes in docs and versioned_docs/version-2.27

[jimmyzhuu]

Thanks for the heads-up. I rebased the branch onto the latest main and updated the versioned docs target from versioned_docs/version-2.27-unstable to versioned_docs/version-2.27.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	Apr 2, 2026 1:52pm

[julian-risch]

Looks good to me! Thank you for opening this pull request @jimmyzhuu . The Vercel Preview looks good to too.