Repository navigation
Publish examples to the docs Cookbook tab with per-PR previews - #7
Merged
Merged
Conversation
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
Adds a deterministic README-to-MDX converter (tools/docs-render), a docs preview workflow that opens a draft OpenHands/docs PR per pull request and reports the Mintlify preview link back, and a publish workflow that keeps a single cookbook-sync PR in OpenHands/docs up to date. Removes the credential probe. Co-authored-by: openhands <openhands@all-hands.dev>
Docs preview✅ Docs preview is ready: https://allhandsai-cookbook-preview-pr-7.mintlify.site
Docs PR: OpenHands/docs#883 (draft preview; never merged, closes with this PR). |
jpshackelford
force-pushed
the
docs-preview-pilot
branch
from
October 3, 2026 18:25
f4f7d4f to
c818d71
Compare
openhands-release-bot Bot
added a commit
to OpenHands/docs
that referenced
this pull request
Oct 3, 2026
Preview of the Cookbook pages produced by OpenHands/enterprise-cookbook#7 (Docs preview pilot: render examples into the OpenHands docs Cookbook), rendered from OpenHands/enterprise-cookbook@c818d71. **Do not merge.** This draft exists only to get a Mintlify preview. It is updated on every push to the source PR and closed when that PR closes. Merged changes reach the docs through a separate `cookbook-sync` PR. _Opened automatically by the docs-preview workflow in OpenHands/enterprise-cookbook._
Only adds example.yaml; the README is unchanged, to show a plain README renders acceptably. Co-authored-by: openhands <openhands@all-hands.dev>
jpshackelford
force-pushed
the
docs-preview-pilot
branch
from
October 3, 2026 18:27
c818d71 to
8c19238
Compare
openhands-release-bot Bot
added a commit
to OpenHands/docs
that referenced
this pull request
Oct 3, 2026
Preview of the Cookbook pages produced by OpenHands/enterprise-cookbook#7 (Docs preview pilot: render examples into the OpenHands docs Cookbook), rendered from OpenHands/enterprise-cookbook@8c19238. **Do not merge.** This draft exists only to get a Mintlify preview. It is updated on every push to the source PR and closed when that PR closes. Merged changes reach the docs through a separate `cookbook-sync` PR. _Opened automatically by the docs-preview workflow in OpenHands/enterprise-cookbook._
jpshackelford
changed the title
jpshackelford
marked this pull request as ready for review
October 3, 2026 18:30
1 of 2 tasks
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Excellent implementation of the docs preview and publishing system. All tests pass, security separation is solid, and the converter is deterministic with comprehensive error handling.
[RISK ASSESSMENT]
- Complexity: MEDIUM - Multi-component system (Node converter, Python orchestrator, GitHub workflows)
- Blast radius: LOW - Only affects docs preview; merges are manual during pilot
- Security posture: LOW - Strong separation between untrusted render (no secrets) and trusted publish (secrets, artifact-only)
- Verdict: APPROVE - Production-ready implementation with excellent test coverage (24 tests)
Key architectural insight: The two-job separation (render without secrets, preview with secrets copying only pre-rendered artifacts) is the correct pattern for processing untrusted PR content while maintaining write access to external repositories.
Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/enterprise-cookbook/actions/runs/37144425266
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Cookbook tab on docs.openhands.dev should be generated from this repository, not maintained as a hand-written copy (OpenHands/docs#604) that drifts from the examples. This PR adds a converter in
tools/docs-renderthat turns each example'sREADME.mdinto a docs page with Mintlify components (callouts, tabs, accordions, cards, code blocks pulled from real files). The conversion is deterministic and has no LLM step, and it fails with a file and line number on anything it doesn't understand. An example is published only once it has anexample.yaml, so the other examples are unaffected until they're migrated one at a time.conversation-tagsis the first, with an unchanged README.Every pull request now gets a draft PR in OpenHands/docs and a comment with Mintlify preview links to each changed page. A
docs-previewstatus fails if the page doesn't render or the docs checks fail. After merge, a separatecookbook-syncPR carries the change to the docs, and for now a human merges it. The job that holds the docs credential (the shared release GitHub App, limited to the docs repo with code and pull-request write access) only copies the rendered files; it never installs dependencies or runs code from the PR. How to publish and write for both GitHub and the docs site is intools/docs-render/README.md.Validation
node --testcases cover each conversion rule and error. They also check thatdocs.jsongets only the Cookbook tab and redirects for removed pages, that a second run changes nothing, and that hand-written files undercookbook/are refused.openhands-release-bot. It waited for the Mintlify deployment and the docs checks (internal links, link-rot), then posted working preview links and setdocs-previewto success.docs-previewwithconversation-tags/README.md:129: link "./NOTES.md" ... does not exist. Dropping that commit force-updated the same docs PR and edited the existing comment in place.cookbook-syncPR. Both run when this merges.This PR was drafted by an AI agent on behalf of the user.