fix: wire Talos API and CLI reference sidebars to show all methods#2604
Conversation
The OSS and OEL sidebars hardcoded only the Talos API overview page and never imported the generated sidebar, so all 18 method entries were dropped during the path-based URL migration (#2603). Import the generated sidebar and spread it in place of the single overview entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The generated OpenAPI sidebar surfaced its raw tag name ("ApiKeys") and a
separate "Introduction" doc flat inside the Talos Reference category. Lift
the methods into a single "API reference" category linked to the overview
page so the navigation reads cleanly.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a hand-maintained CLI reference sidebar tree mirroring the `talos --help` command hierarchy and wire it into the OSS and OEL sidebars in place of the single flat `talos` command entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
aeneasr
requested review from
piotrmsc,
unatasha8,
vinckr,
wassimoo and
zepatrik
as code owners
📝 WalkthroughWalkthroughThis PR refactors Talos documentation navigation by extracting the CLI reference into a dedicated sidebar definition file and updating both OEL and OSS main sidebars to import and integrate the new CLI reference alongside consolidated API references, replacing direct doc-ID references with organized category structures. ChangesTalos CLI and API Reference Navigation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
sidebars-oel.ts (2)
10-22: 💤 Low valueConsider whether the overview doc should also appear as the first item.
The generated
talosApiReferencecategory links to the overview page but does not include it as the first item in theitemsarray. Based on learnings, the intentional pattern in sidebar files is to have a doc appear both as the categorylinkand as the first entry initemsto ensure it's visible both as the landing page and in the sidebar list.However, the comment explicitly states the intent is to "read cleanly instead of exposing the raw OpenAPI tag name," suggesting the omission is deliberate. Please confirm whether users can still easily discover and access the overview page with this structure, or if it should be added to
itemsfor consistency with the established pattern.Based on learnings: In sidebar config files, having a doc listed both as a category
linkand as the first entry in the same sidebaritemsarray is intentional, ensuring the page appears as the visible category landing and is also explicitly present in the sidebar list.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@sidebars-oel.ts` around lines 10 - 22, The talosApiReference category currently sets link: { type: "doc", id: "talos/reference/api/ory-talos-api" } but omits that same doc from the items list, breaking the established pattern of listing the overview page as the first item; update talosApiReference so its items array begins with the overview doc (id "talos/reference/api/ory-talos-api") followed by the existing flatMap result from talosApiSidebar, ensuring the overview appears both as the category landing (link) and as the first sidebar entry while preserving the rest of the generated items.
10-22: ⚡ Quick winConsider extracting the duplicated
talosApiReferencelogic.The
talosApiReferenceconstruction logic (lines 10-22 in this file) is duplicated identically insidebars-oss.ts(lines 4-16). Extracting this shared logic into a separate module (e.g.,docs/talos/reference/api/api-reference-builder.ts) would improve maintainability and ensure both sidebars stay in sync when the API sidebar structure changes.♻️ Suggested refactor to extract shared logic
Create a new file
docs/talos/reference/api/api-reference-builder.ts:import talosApiSidebar from "./sidebar" // The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. // Lift the methods into a single "API reference" category linked to the overview page so the // navigation reads cleanly instead of exposing the raw OpenAPI tag name. export const talosApiReference = { type: "category", label: "API reference", link: { type: "doc", id: "talos/reference/api/ory-talos-api" }, items: talosApiSidebar.flatMap((item: any) => typeof item === "object" && "items" in item && Array.isArray(item.items) ? item.items : [], ), }Then update both sidebar files to import it:
-import talosApiSidebar from "./docs/talos/reference/api/sidebar" +import { talosApiReference } from "./docs/talos/reference/api/api-reference-builder" import talosCliReference from "./docs/talos/reference/cli/sidebar" - -// The generated Talos API sidebar is [overview doc, { category "ApiKeys", items: [...methods] }]. -// Lift the methods into a single "API reference" category linked to the overview page so the -// navigation reads cleanly instead of exposing the raw OpenAPI tag name. -const talosApiReference = { - type: "category", - label: "API reference", - link: { type: "doc", id: "talos/reference/api/ory-talos-api" }, - items: talosApiSidebar.flatMap((item: any) => - typeof item === "object" && "items" in item && Array.isArray(item.items) - ? item.items - : [], - ), -}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@sidebars-oel.ts` around lines 10 - 22, Duplicate construction of talosApiReference should be extracted into a shared module: create a new module that imports talosApiSidebar and exports a single talosApiReference object (same shape and flatMap logic as currently used), then replace the inline talosApiReference definitions in both sidebar files to import that exported talosApiReference; update any references to talosApiReference to use the shared export so both sidebars stay in sync.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@sidebars-oel.ts`:
- Around line 10-22: The talosApiReference category currently sets link: { type:
"doc", id: "talos/reference/api/ory-talos-api" } but omits that same doc from
the items list, breaking the established pattern of listing the overview page as
the first item; update talosApiReference so its items array begins with the
overview doc (id "talos/reference/api/ory-talos-api") followed by the existing
flatMap result from talosApiSidebar, ensuring the overview appears both as the
category landing (link) and as the first sidebar entry while preserving the rest
of the generated items.
- Around line 10-22: Duplicate construction of talosApiReference should be
extracted into a shared module: create a new module that imports talosApiSidebar
and exports a single talosApiReference object (same shape and flatMap logic as
currently used), then replace the inline talosApiReference definitions in both
sidebar files to import that exported talosApiReference; update any references
to talosApiReference to use the shared export so both sidebars stay in sync.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 51e8700b-bdec-46d2-9486-d16a05713e92
📒 Files selected for processing (3)
docs/talos/reference/cli/sidebar.tssidebars-oel.tssidebars-oss.ts
Related Issue or Design Document
Improves the documentation, no issue reference required.
The Talos reference sidebar was broken: the generated API reference sidebar was never wired into the OSS/OEL navigation, so only the overview page showed instead of all 18 API methods, and the CLI reference exposed only a single flat
taloscommand entry. This PR wires the generated Talos API reference sidebar into both the OSS and OEL sidebars and groups the methods under a clean "API reference" category linked to the overview page. It also adds a hand-maintained CLI reference sidebar (docs/talos/reference/cli/sidebar.ts) that mirrors thetalos --helpcommand hierarchy and replaces the flat CLI entry in both sidebars. The result is a complete, navigable Talos API and CLI reference.Checklist
🤖 Generated with Claude Code
Summary by CodeRabbit