📖✨：publish the API reference through the portal - #10
Merged
Merged
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Advanced Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (92)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📝 WalkthroughWalkthroughThe SDK now generates and validates Markdown API references, packages versioned documentation artifacts, uploads them for published releases, and documents portal import procedures. It also reformats 82 JSDoc examples without changing runtime behavior. ChangesAPI documentation pipeline
Estimated code review effort: 3 (Moderate) | ~25 minutes Merge Risk: ⚪ Minimal · up to This change adds validated, versioned API-documentation artifacts to published releases and corrects JSDoc example rendering without runtime API changes. The documentation pipeline and release packaging are ready to merge. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Member
Author
|
@coderabbitai full review |
✅ Action performedFull review finished. |
DerekNonGeneric
force-pushed
the
codex/sdk-markdown-api
branch
from
September 10, 2026 01:06
60f577b to
4bf620c
Compare
DerekNonGeneric
changed the title
The OpenINF portal renders this SDK's API reference in its own documentation layout, at /docs/sdk/<version>/api/, rather than serving TypeDoc's HTML. That makes the generated Markdown a product artifact with a consumer, so TypeDoc now emits Markdown and a navigation tree, and a release packages both with a manifest naming the version and the commit they describe. The consumer is strict. It maps every generated path onto a public URL, strips the chrome TypeDoc writes above each page, reads each page's title from the heading underneath, and rewrites every internal link. Anything it cannot map, it refuses. `docs:check` applies those same rules here, against the same files, so a page the portal would refuse fails the pull request that introduced it rather than the release that would have shipped it. CI packages the corpus too, under a placeholder version, because a release is otherwise the only thing that ever runs the packaging. TypeDoc reads its overview from `documentation/api-overview.md` rather than the repository README, which links to contributor and release instructions that have no meaning on the portal. Sources are disabled: the paths they would name are the SDK's, not the reader's. The release workflow builds the artifact only on a run that actually published, since a run that just opens the version PR has no release to describe, and attaches it for a maintainer to vendor into the portal. RELEASING.md describes that handoff. Rendering the corpus for the first time made eighty-two broken examples visible. Those JSDoc comments opened their fenced code block on the `@example` line itself, and TypeDoc reads the remainder of such a tag as text rather than as a block: it wrapped each one in a second fence and left the comment's leading asterisk in the first line of code. They ship in the declaration files too, so editors showed the same thing. The nine comments that already opened the fence on the next line rendered correctly, which is what the other eighty-two now do. Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is> Assisted-by: Claude-Code:claude-opus-5
DerekNonGeneric
force-pushed
the
codex/sdk-markdown-api
branch
from
September 10, 2026 01:31
4bf620c to
5535495
Compare
DerekNonGeneric
added
the
🚀 Status: Commit Queue
openinf-commit-queue
Bot
removed
the
🚀 Status: Commit Queue
|
The commit queue did not land this. See https://github.com/OpenINF/sdk/actions/runs/34428554446 — the label has been taken back off, so re-applying it is a deliberate second try. |
DerekNonGeneric
added a commit
that referenced
this pull request
Sep 11, 2026
The OpenINF portal renders this SDK's API reference in its own documentation layout, at /docs/sdk/<version>/api/, rather than serving TypeDoc's HTML. That makes the generated Markdown a product artifact with a consumer, so TypeDoc now emits Markdown and a navigation tree, and a release packages both with a manifest naming the version and the commit they describe. The consumer is strict. It maps every generated path onto a public URL, strips the chrome TypeDoc writes above each page, reads each page's title from the heading underneath, and rewrites every internal link. Anything it cannot map, it refuses. `docs:check` applies those same rules here, against the same files, so a page the portal would refuse fails the pull request that introduced it rather than the release that would have shipped it. CI packages the corpus too, under a placeholder version, because a release is otherwise the only thing that ever runs the packaging. TypeDoc reads its overview from `documentation/api-overview.md` rather than the repository README, which links to contributor and release instructions that have no meaning on the portal. Sources are disabled: the paths they would name are the SDK's, not the reader's. The release workflow builds the artifact only on a run that actually published, since a run that just opens the version PR has no release to describe, and attaches it for a maintainer to vendor into the portal. RELEASING.md describes that handoff. Rendering the corpus for the first time made eighty-two broken examples visible. Those JSDoc comments opened their fenced code block on the `@example` line itself, and TypeDoc reads the remainder of such a tag as text rather than as a block: it wrapped each one in a second fence and left the comment's leading asterisk in the first line of code. They ship in the declaration files too, so editors showed the same thing. The nine comments that already opened the fence on the next line rendered correctly, which is what the other eighty-two now do. Signed-off-by: Derek Lewis <DerekNonGeneric@inf.is> Assisted-by: Claude-Code:claude-opus-5 PR-URL: #10
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
Re-opens against this repository the work that was proposed where this SDK was developed before the move, and closes the gap that stopped it being publishable.
The OpenINF portal renders this SDK's API reference in its own documentation layout at
/docs/sdk/<version>/api/, rather than serving TypeDoc's HTML. So TypeDoc now emits Markdown and a navigation tree, and a release packages both with a manifest naming the version and the commit they describe. The portal side is OpenINF/openinf.github.io#1895.What changed since the original
A release now produces something. The original generated the Markdown and validated it, but nothing ever built the versioned artifact the portal imports, and no workflow ever handed one over.
pnpm run docs:artifactbuilds it; the release workflow builds it on a run that actually published and attaches it as sdk-api-docs; RELEASING.md describes the handoff. The version is read from the workspace rather than passed in, so a released artifact can only carry the version that was released.docs:checknow checks what the portal actually enforces. It previously looked for private references and confirmed link targets existed on disk. The portal is stricter, and each of its rules now runs here against the same files:README.md,packages.md, or@openinf/<package>/fails here rather than there82 broken code examples are fixed. Rendering the corpus for the first time made these visible: those comments opened their fenced block on the
@exampleline itself, which TypeDoc reads as text rather than as a block. Each one came out wrapped in a second fence with the comment's leading asterisk still in the first line of code. They ship in the declaration files too, so editors showed the same thing.CI packages the artifact as well as generating it, under a placeholder version, because a release is otherwise the only thing that ever runs the packaging.
TypeDoc's
invalidPathcheck is off, with the reason recorded intypedoc.json. The overview links to the generated package index, which TypeDoc reads as a relative file to copy and cannot find. It is that page's only inbound link and it is correct in the output, so the link stays anddocs:checkvalidates every generated link instead.Validation
Run against the real ten-package corpus, 331 pages:
pnpm run build,pnpm run lint,pnpm run test— 10 packages, 0 failurespnpm run docs:build— no TypeDoc warnings or errorspnpm run docs:check— 331 pages pass; each rule was also confirmed to fail on a deliberately broken corpuspnpm run docs:artifact— refuses to guess a version while the workspace packages disagree, as it will untilchangeset versionrunspnpm run lint:format,lint:knip,lint:spelling,lint:packagespnpm install --frozen-lockfileEnd to end against the portal branch: the artifact this produces imports cleanly, and the portal builds all 331 pages with no
.mdlinks left in the rendered HTML.🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features