Add YAML file support to sync_code_blocks.py

[xingyaoww]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

Problem

The pr-review.mdx file had an empty YAML code block that wasn't rendering properly. Investigation revealed that the auto-sync script (/docs/.github/scripts/sync_code_blocks.py) only supported Python files (.py), not YAML files (.yml).

Solution

Extended the sync script to support YAML files:

1. Updated sync_code_blocks.py:

   • Modified extract_code_blocks() to detect both Python and YAML code blocks
   • Pattern matching now handles:
     • Python: ```python ... examples/path/file.py
     • YAML: ```yaml ... examples/path/file.yml
   • Updated function signatures to include language parameter
   • Made code block reconstruction language-aware

2. Restored pr-review.mdx:

   • Added back the YAML code block with correct path: examples/03_github_workflows/02_pr_review/workflow.yml
   • Ran sync script to populate with actual workflow content (114 lines)
   • Code block now displays the full GitHub Actions workflow

Testing

• ✅ Verified sync script works with existing Python files (all in sync)
• ✅ Verified YAML sync successfully populates pr-review.mdx
• ✅ No breaking changes to existing functionality
• ✅ Script now supports both .yml and .yaml extensions

Impact

This enables auto-syncing of GitHub workflow examples and other YAML configuration files throughout the documentation, ensuring they stay up-to-date with the source repository.

[enyst]

Should we say 1.0.0 ? 🤔

[enyst]

Or install from pypi

[xingyaoww]

This is actually the example workflow in the SDK repo, not this repo.

cc @simonrosenberg - maybe we do want to point it to latest pypi wheel

[enyst]

Ah, sure 😅

[enyst]

@OpenHands What do you think about the PR reviewer workflow requesting "openhands-agent", is there anything else the user needs to do to make it work on their own repos?
/codereview-roasted

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Summary of my response to the question

• Requesting “openhands-agent” only works if that GitHub account exists in the target repo and can be requested as a reviewer. Most users won’t have that, so they should either:

  • Use the label trigger (“review-this”), which works universally, or
  • Change the check to a reviewer handle they control and ensure that account is a collaborator/team with access. Better yet, make the reviewer handle configurable (e.g., repo variable/secret).

• Required setup for users’ repos:

  • Add LLM_API_KEY as a repo secret.
  • Set LLM_MODEL (and LLM_BASE_URL if using a custom gateway), or ensure the script has sensible defaults.
  • The workflow’s permissions (pull-requests: write, issues: write) are correct for posting comments.

• Forks caveat:

  • For PRs from forks, pull_request workflows have read-only GITHUB_TOKEN and no secrets. If they need to support forks, consider pull_request_target with proper hardening, or keep it as a maintainer-only trigger (label or reviewer request by maintainers).

Recommendation

• Keep the label trigger as the default path that works everywhere.
• If a “request reviewer” UX is desired, parameterize the reviewer handle and document that the account must have repo access; optionally support team triggers via requested_team.slug.

_{View full conversation}

[enyst]

This looks correct to me (right?), maybe a bit too verbose, but idk, readable.

WDYT, should we keep it? @xingyaoww @simonrosenberg

[xingyaoww]

Seems useful info to keep?

[enyst]

LGTM, I'm very happy to see openhands-agent documented and working!