feat(appkit-docs): sync via shallow git clone at build time#58
Open
feat(appkit-docs): sync via shallow git clone at build time#58
Conversation
2 tasks
pkosiec
force-pushed
the
pkosiec/appkit-docs-sync
branch
from
7533ac7 to
a17977a
Compare
Replace the manual tarball-based AppKit docs sync with a shallow git clone of the main branch that runs automatically as a prebuild step. Docs are now generated at build time instead of being committed to git. Key changes: - Rewrite sync-appkit-docs.mjs to clone from main with sparse checkout - Output docs to docs/appkit/latest/ (instead of v0/) - Skip with informational log when docs already exist locally - Support future Docusaurus versioned_docs if AppKit adopts versioning - Add prebuild/prestart lifecycle hooks for automatic sync - Update sidebar to discover latest/ and version-* directories - Add generated paths to .gitignore and .prettierignore - Add explicit sync step to CI workflow Co-authored-by: Isaac
…nvention - Update DocExample styles href from v0 to latest - Rewrite getAppKitChannelOptions to deduplicate by channel path segment - Hide VERSION dropdown when only one channel exists (> 1 check) Co-authored-by: Isaac
- Fix stale error message referencing removed `v0` argument in DocExample - Harden isAlreadySynced() to check all 3 outputs (docs, examples, styles) - Wrap temp directory in try/finally so it's cleaned up on failure - Change fail() to throw so cleanup runs before exit - Add 2-minute timeout to spawned git commands - Remove unnecessary appKitItems alias in sidebars Co-authored-by: Isaac
Prettier 3.8 changed the default for JSON to tabs. Pin useTabs: false and tabWidth: 2 to maintain consistent formatting across the repo. Co-authored-by: Isaac
pkosiec
force-pushed
the
pkosiec/appkit-docs-sync
branch
from
403810e to
11b85e7
Compare
Allow overriding the appkit git remote URL and branch via environment variables. Defaults remain unchanged (github.com/databricks/appkit, main). This enables CI pipelines in the appkit repo to validate that docs changes on a PR branch don't break the devhub build, and supports forks where the remote URL differs. Co-authored-by: Isaac
2 tasks
- Validate APPKIT_BRANCH and APPKIT_REMOTE before passing to git clone to prevent flag injection (e.g. --upload-pack=/bin/sh). - Replace SIGTERM-only checks with generic signal check in run() and runCapture() to catch SIGKILL, SIGSEGV, etc. Co-authored-by: Isaac
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
1 participant
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.
Summary
Replace committed AppKit docs, examples, and compiled styles with build-time sync from the appkit repo.
How it works
scripts/sync-appkit-docs.mjsruns automatically viaprebuild/prestarthooks on first build or dev start:main(sparse checkout) into a temp dirdocs/appkit/latest/, examples tosrc/components/doc-examples/, compiles styles tostatic/appkit-preview/latest/npm run sync:appkit-docsto force re-syncAll generated paths are gitignored. Override clone source via
APPKIT_REMOTE/APPKIT_BRANCHenv vars.The script and sidebar are ready for doc versioning — when appkit ships
versioned_docs/, they'll be picked up automatically asversion-*/channels alongsidelatest.Other changes
.prettierrcto pin 2-space indent (Prettier 3.8 defaults to tabs for JSON)Design note
Live
<DocExample>previews are tied to the single installed@databricks/appkit-uipackage, since npm supports only one version at a time. When multiple doc versions ship, older versions will show code blocks only — no live preview.Known limitations
@databricks/appkit-uiversion is pinned manually. Docs and examples sync from appkitmain, but the npm package used for live component rendering is pinned inpackage.json. These can drift. Once@databricks/appkit-uiis allowlisted on the npm proxy, the sync script should auto-update the dep to match the cloned version.Test plan
npm run build— syncs and buildsnpm run buildagain — skips, no network callnpm run sync:appkit-docs— force re-sync works.source-refhas SHA + dateScreenshot