[FEATURE] Docs preview for schema changes#473
Open
John McCall (lowlydba) wants to merge 27 commits intodevfrom
Open
[FEATURE] Docs preview for schema changes#473John McCall (lowlydba) wants to merge 27 commits intodevfrom
John McCall (lowlydba) wants to merge 27 commits intodevfrom
Conversation
Signed-off-by: John McCall <john@overturemaps.org>
Add inputs to the generate-schema-docs action to check out OvertureMaps/schema (schema-ref, schema-path) and run overture-codegen from that checked-out repo (use its .python-version and working directory). Update the schema PR preview workflow to use env variables (STAGING_URL, PREVIEW_PATH, DOCS_PATH) instead of hardcoded _docs and staging URLs, propagate DOCS_PATH to checkout, Node setup, build, artifact paths, and update S3/CloudFront sync and the preview link to use the new preview path. These changes allow generating docs from the external schema repo and make preview deployment paths configurable for PR previews. Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
changed the title
Pass --all-packages to uv sync in the generate-schema-docs action so all schema packages are installed before generating docs. Also add a temporary ref (jmccall-schema-docs-builds) to the schema-pr-preview workflow to point the docs preview at a specific branch; a TODO notes this should be removed before merging. Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Rename input schema-path to schema-checkout-path for clarity, add a skip-checkout input (default false) and conditionally skip the actions/checkout step. Update all steps to use the new schema-checkout-path (checkout path, python-version-file, working-directory) and loosen uv sync to explicitly sync overture-schema and overture-schema-codegen (remove --all-packages). Update workflow to pass skip-checkout: 'true' when the repo is already checked out at the workspace root. Signed-off-by: John McCall <john@overturemaps.org>
Rename the generate-schema-docs action input from schema-checkout-path to schema-path and update all usages. Adjusted input descriptions (including skip-checkout) and replaced references in action.yml for checkout path, python-version-file, and working-directory so the same variable is used for checkout destination, Python version lookup, package installation, and docs generation. Also updated schema-pr-preview workflow to pass schema-path: . and rely on skip-checkout when the repo is already checked out at the workspace root. Signed-off-by: John McCall <john@overturemaps.org>
🗺️ Schema reference docs preview is live!
Note ♻️ This preview updates automatically with each push to this PR. |
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
Signed-off-by: John McCall <john@overturemaps.org>
John McCall (lowlydba)
temporarily deployed
to
staging
GitHub Actions
Inactive
John McCall (lowlydba)
requested review from
Copilot,
Jennings Anderson (jenningsanderson) and
Seth Fitzsimmons (mojodna)
There was a problem hiding this comment.
Pull request overview
Adds GitHub Actions workflows to build and deploy a “slim” docs preview for schema pull requests to the staging site, and cleans up the preview on PR close.
Changes:
- Introduces a PR-triggered workflow that checks out
OvertureMaps/docs, generates schema reference markdown, builds the Docusaurus site, uploads an artifact, and deploys to S3/CloudFront with a sticky PR comment containing the preview link. - Adds a cleanup workflow to delete the PR preview from S3 and invalidate CloudFront when the PR is closed.
- Fixes the default
aws_account_idinput in the reusable Python package version check workflow to be a quoted string.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| .github/workflows/schema-pr-preview.yml | Build + deploy staging docs preview for schema PRs and comment back with the preview URL. |
| .github/workflows/schema-pr-preview-cleanup.yml | Remove the PR preview from S3 and invalidate CloudFront on PR close. |
| .github/workflows/reusable-check-python-package-versions.yaml | Quotes the aws_account_id default input value. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Jennings Anderson (@jenningsanderson) I've opened a new pull request, #481, to work on those changes. Once the pull request is ready, I'll request review from you. |
This was referenced Mar 23, 2026
|
Jennings Anderson (@jenningsanderson) I've opened a new pull request, #482, to work on those changes. Once the pull request is ready, I'll request review from you. |
Jennings Anderson (jenningsanderson)
previously approved these changes
Mar 23, 2026
Collaborator
Jennings Anderson (jenningsanderson)
left a comment
Jennings Anderson (jenningsanderson)
left a comment
There was a problem hiding this comment.
LGTM — I just responded to some of CoPilot's ideas and asked it to implement just one of them...
Signed-off-by: John McCall <john@overturemaps.org>
Contributor
Author
Already did it! Good callout though, this definitely heavy enough of a job to have concurrency for |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Author
|
Jennings Anderson (@jenningsanderson) Copilot's |
Connie Sun (connieksun)
approved these changes
Mar 24, 2026
Connie Sun (connieksun)
left a comment
Connie Sun (connieksun)
left a comment
There was a problem hiding this comment.
Approving as public reviewer ✅
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
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.
Description
Allows for slim builds* of the docs repo for pull requests to the schema repo. Schema docs are built from the codegen cli.
* Slim builds are controlled via the SCHEMA_PREVIEW env var to bypass community and blog posts.
Reference
Resolves https://github.com/OvertureMaps/schema-wg/issues/416
Testing
This functionality can be directly tested within this pull request via the Docs build preview comments. This comment will appear on all PRs as a convenience going forward, with the goal that eventually we can directly publish the docs with the generated schema documentation files.