Uh oh!
There was an error while loading. Please reload this page.
feat(scripts): let build-docs fetch a docs ref from GitHub - #12
Merged
Conversation
`findDocsPath()` resolved five ways, all filesystem — so regenerating src/docs/data.ts meant having a docs.auto.dev checkout and pointing .env at a path on one person's machine. Nobody else could reproduce the output, and the committed result could drift from the docs it claims to mirror with nothing to catch it. Adds DOCS_REF as one more resolution strategy in the same function: DOCS_REF=main pnpm build:docs && pnpm build:docs-data DOCS_REF=feat/no-trials-copy pnpm build:docs It shallow-clones at that ref and returns the path, so everything downstream is untouched — the rest of the script only ever needed a directory. DOCS_REPO overrides the repo if it ever moves. Precedence: a CLI arg still wins, then DOCS_REF, then DOCS_PATH. A ref is a more specific request than a path, so it takes priority over one; an explicit argument beats both. Uses ambient git credentials rather than plumbing a token: a developer's existing auth locally, a token-backed remote in CI. docs.auto.dev is private and this SDK is public, so a workflow using this needs a cross-org read token. That is stated in the code rather than worked around, because there is no way around it. Verified against drivly/docs.auto.dev@feat/no-trials-copy: fetched, converted all 12 product docs, and the regenerated data.ts dropped from 12 "Starter" availability lines to 0 with 12 "**Free**:" in their place — matching drivly/docs.auto.dev#27. data.ts itself is deliberately NOT in this commit. Generating committed content from an unmerged branch pins it to a state that can still change; regenerate from main once #27 lands. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`pnpm build:docs DOCS_REF=main` is the natural thing to type, and it failed with: Product docs not found at: DOCS_REF=main/content/docs/v2/products which reports the symptom rather than the mistake. An env var placed after the command arrives as a positional, and the CLI-arg branch is checked first, so it was taken as a path. Now it says what to do instead: "DOCS_REF=main" looks like an environment variable, not a path. Put it before the command: DOCS_REF=main pnpm build:docs Matches on SCREAMING_CASE followed by `=`, so real paths are unaffected — verified all three forms still behave: bare path, DOCS_REF env var, and the mistyped version. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
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 freeto 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.
Tooling, not rollout copy — separate from #11 so that one stays merge-ready.
Problem
findDocsPath()resolves five ways and every one is filesystem: CLI arg →DOCS_PATH→.env→ afindunder~/Workspace→ sibling directory.So regenerating
src/docs/data.tsrequired a local docs.auto.dev checkout with.envpointing at a path on one person's machine. Nobody else could reproduce the output, and the committed result could drift from the docs it mirrors with nothing to catch it.Change
One more strategy in the same function:
DOCS_REF=main pnpm build:docs && pnpm build:docs-data DOCS_REF=feat/no-trials-copy pnpm build:docsShallow-clones at that ref and returns the path — everything downstream is untouched, since the rest of the script only ever needed a directory.
DOCS_REPOoverrides the repo if it moves.Precedence: CLI arg →
DOCS_REF→DOCS_PATH→ … A ref is a more specific request than a path, so it beats one; an explicit argument beats both.On credentials
Uses ambient git auth rather than plumbing a token — a developer's existing credentials locally, a token-backed remote in CI.
docs.auto.dev is private and this SDK is public, so any workflow using this needs a cross-org read token as a secret. That's stated in the code rather than worked around, because there isn't a way around it. Wiring that up is a separate access decision; this change is what makes it a config step instead of a rewrite.
Verified
Ran against
drivly/docs.auto.dev@feat/no-trials-copy: fetched, converted all 12 product docs, and the regenerateddata.tswent from 12Starteravailability lines to 0, with 12**Free**:in their place — matching drivly/docs.auto.dev#27.data.tsis not in this PRDeliberately. Generating committed content from an unmerged branch pins it to a state that can still change. Once docs#27 lands, regenerate from
main— one command, and now reproducible by anyone.Worth knowing either way: the generator only reads
content/docs/v2/products/, so docs#27's changes togetting-started.mdx,index.mdxanderrors.mdxnever reachdata.ts. Only the 12 product files do.