feat: vendor doc-gen tooling and build from the spec's openapi.yaml release asset - #2
Open
eddie-knight wants to merge 1 commit into
Open
feat: vendor doc-gen tooling and build from the spec's openapi.yaml release asset#2eddie-knight wants to merge 1 commit into
eddie-knight wants to merge 1 commit into
Conversation
…elease asset The site previously cloned gemaraproj/gemara and ran the markdown tooling (openapi2md, lexicon2md, termlinker, parse-nav.sh) out of that checkout's cmd/ directory. Those tools only exist to render this site, so they now live here under tools/ as their own Go module. The build input is now the spec's OpenAPI projection instead of a source checkout: - make gendocs downloads openapi.yaml from the spec release named by GEMARA_REF (default: latest). GEMARA_DIR=/path/to/gemara still generates it locally via the spec's cue2openapi for unreleased schema work, and GEMARA_OPENAPI=/path/to/file uses a pre-generated copy. - deploy.yml downloads the release asset for the resolved ref, falling back to clone-and-generate for refs that predate the asset (and for branch refs like main). The spec repo publishes the openapi.yaml asset starting with its next release; the fallback keeps builds working against older tags. Signed-off-by: Eddie Knight <knight@linux.com>
jpower432
approved these changes
Jul 28, 2026
| echo "Downloaded openapi.yaml from release $REF" | ||
| else | ||
| echo "::warning::No openapi.yaml release asset for $REF; generating from a spec checkout" | ||
| git clone --depth 1 --branch "$REF" https://github.com/gemaraproj/gemara .gemara-spec |
Contributor
There was a problem hiding this comment.
Nit
Suggested change
| git clone --depth 1 --branch "$REF" https://github.com/gemaraproj/gemara .gemara-spec | |
| timeout 120 git clone --depth 1 --branch "$REF" https://github.com/gemaraproj/gemara .gemara-spec |
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.
🤖 Summary
Makes the website self-contained: the markdown rendering tools move into this repo, and the build consumes the spec's OpenAPI projection (
openapi.yaml) instead of cloning the spec repo and running its CLI.Merge this before gemaraproj/gemara's website-removal PR — that PR deletes the tools this repo previously ran out of the spec checkout.
Changes
tools/— new Go module (github.com/gemaraproj/website/tools) vendoringopenapi2md,lexicon2md,termlinker, and the nav-parsing scripts from the spec repo'scmd/, with flag defaults adjusted for this repo's root-level layout. TheOpenAPISpectypes consumed byopenapi2mdare mirrored inopenapi_types.go.Makefile—gendocsnow acquiresgenerated/openapi.yaml(in order of precedence):GEMARA_OPENAPI=<file>(pre-generated copy),GEMARA_DIR=<spec checkout>(runs the spec'scue2openapilocally, for unreleased schema work), or downloads the release asset forGEMARA_REF(default:latest). All markdown rendering now runs fromtools/. The acquisition is a file target, so CI can pre-populate the file and skip it..github/workflows/deploy.yml— downloads theopenapi.yamlasset for the resolved spec ref; falls back to clone-and-generate for refs that predate the asset (all releases up to and including the current latest) and for branch refs likemain.README.md— build documentation updated to match.Verification
go build ./... && go vet ./...intools/pass.make gendocs GEMARA_DIR=../gemararenders all 16 schema pages, the definitions table, and term links across 85 files;make cleanupreturns the tree to clean.Transition notes
openapi.yamlon its next release (companion PR); until then every CI build takes the fallback path, which keeps working because old spec tags still contain the full CLI.repository_dispatchcontract (gemara-release,client_payload.ref) is unchanged.