feat(docs): add API reference generation and PR CI - #1
Merged
Merged
Conversation
Add internal/docs Go tool that shells out to gomarkdoc@v1.1.0 with --repository.default-branch main, wipes docs/api/ and rewrites a single docs/api/reference.md, then post-processes to strip #Lxx line anchors so the committed reference is a byte-stable artifact of the current commit. New Makefile targets: docs / docs-check / lint. docs-check is stubbed and implemented in the follow-up task. Discovery spike observations (retained in the task ledger): - source links only appear with explicit --repository.* flags - all 3802 QoderAI URLs land on blob/main/... with #Lxx(-Lyy) anchors - two runs at the same commit + Go toolchain are byte-identical - no timestamps / absolute paths / user identifiers observed Task: 1789870148
Regenerates docs/api/reference.md, then runs a four-stage gate:
1. `git diff --exit-code -- docs/api` for drift
2. every QoderAI blob URL must be on 'main' ref without #Lxx anchors
3. core public surface (forward.Client / managed.Client / apierror.Error
plus both NewClient constructors) must appear in the output
4. relative markdown links must resolve (fenced code blocks are excluded
so Go generics don't false-positive)
Drift RED verified by appending a temporary GoDoc comment to
forward/client.go — check surfaced the diff and exited non-zero.
Task: 1789870148
Extends README ## Development with make lint + a new API reference subsection pointing at docs/api/reference.md and the gomarkdoc-backed regeneration flow. Also gofmt-aligns comments in internal/docs/check.go so make lint passes cleanly. Task: 1789870148
.github/workflows/ci.yml runs on pull_request and push(main) with contents:read scope. Matrix job iterates Go 1.23.x (module minimum) and 1.26.x, invoking make lint (gofmt + go vet) → make build → make test (offline). docs-check runs on a single pinned Go version (1.26.x) — go/doc rendering varies across Go versions so drift must be judged against exactly one toolchain. Verified locally: all four commands green. Task: 1789870148
Task: 1789897112
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
Testing
make lintmake buildmake testmake docs-check