polish(nav): proper sidebar labels for SDK package groups#67
Conversation
Sidebar groups for Rust were rendering as raw dir names (`resq-ai`, `resq-bin`, `resq-cli`, `resq-dsa`, `resq-tui`), out of step with the rest of the site: - Mintlify auto-titles leaf pages from filenames (`resq-clean.md` → "Resq clean") - TypeScript groups are already clean (Analytics, HTTP, ...) - .NET groups already use the canonical dotted form Add a smart label formatter that: - Recognises common acronyms (AI, CLI, DSA, TUI, MCP, HTTP, JSON, ...) and upper-cases them - Recognises the brand `resq` and renders it as `ResQ` - Title-cases the rest, hyphens → spaces - Passes dotted names through verbatim (preserves .NET casing) Apply in: - automation/source-repo-templates/api-docs.rust.yml splice + per-crate stub generation (sidebarTitle frontmatter so leaves also pick up the polished labels) - scripts/splice-sdk-nav.py (used for local re-splice across all five languages) Re-spliced docs.json + injected sidebarTitle frontmatter on the six existing binary-only Rust stubs so the live nav reflects the labels immediately. Result (Rust): README ResQ Clean ResQ Deploy ResQ Flame ResQ Health ResQ Logs ResQ Perf ResQ AI ▸ ResQ Bin ▸ ResQ CLI ▸ ResQ DSA ▸ ResQ TUI ▸ The TypeScript template's splice has the same structure but already produces clean labels (no acronyms in the sub-group names); a follow-up PR can apply label_for there too if names like `rate-limiting` should become `Rate Limiting` instead of the current Mintlify-default treatment.
github-actions
Bot
added
area:content
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (9)
✨ Finishing Touches🧪 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request implements a label_for utility to standardize sidebar labels across documentation, ensuring proper casing for acronyms and brand names. Changes include updates to CI templates, navigation scripts, and frontmatter in Markdown files, alongside a large-scale update to group names in docs.json. Feedback focuses on expanding the acronym list to include project-specific terms like HCE and PDIE, enhancing the label logic to support underscores and specific dotted naming conventions, and reducing code duplication between the CI configuration and the standalone Python script.
| ACRONYMS = { | ||
| "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp", | ||
| "ipfs", "grpc", "http", "url", "json", "yaml", "xml", | ||
| "sql", "css", "html", "io", | ||
| } |
There was a problem hiding this comment.
The ACRONYMS list is missing several project-specific and common technical acronyms that appear in the documentation (e.g., HCE, PDIE, DTSOP, RPC). Adding these will ensure they are correctly capitalized in the sidebar, matching the "polish" goal of this PR.
ACRONYMS = {
"ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp",
"ipfs", "grpc", "http", "url", "json", "yaml", "xml",
"sql", "css", "html", "io", "hce", "pdie", "dtsop", "rpc",
}| def label_for(name: str) -> str: | ||
| if "." in name: | ||
| return name | ||
| out = [] | ||
| for part in name.split("-"): | ||
| lower = part.lower() | ||
| if lower in BRAND: | ||
| out.append(BRAND[lower]) | ||
| elif lower in ACRONYMS: | ||
| out.append(part.upper()) | ||
| else: | ||
| out.append(part.capitalize()) | ||
| return " ".join(out) |
There was a problem hiding this comment.
The label_for function has two opportunities for improvement:
- Underscore Handling: Rust and Python modules often use underscores (e.g.,
count_min). Currently, these would be rendered asCount_mininstead ofCount Min. - Dot Heuristic: The check
if "." in nameis too broad. It correctly preserves.NETnamespaces likeResQ.Blockchain, but it prevents polishing of lowercase TypeScript groups likeafter.fnorafter.types. Refining this to only skip names with mixed casing (like the.NETexamples) would fix this.
def label_for(name: str) -> str:
# Pass through names that already have mixed casing (e.g. .NET namespaces)
if "." in name and not name.islower():
return name
out = []
# Handle both hyphens and underscores for consistent spacing
for part in name.replace("_", "-").split("-"):
lower = part.lower()
if lower in BRAND:
out.append(BRAND[lower])
elif lower in ACRONYMS:
out.append(part.upper())
else:
out.append(part.capitalize())
return " ".join(out)| ACRONYMS = { | ||
| "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp", | ||
| "ipfs", "grpc", "http", "url", "json", "yaml", "xml", | ||
| "sql", "css", "html", "io", | ||
| } | ||
| BRAND = {"resq": "ResQ"} | ||
|
|
||
| def label_for(name): | ||
| # Pass dotted names through (e.g. .NET-style | ||
| # `ResQ.Blockchain` already carry canonical casing). | ||
| if "." in name: | ||
| return name | ||
| out = [] | ||
| for part in name.split("-"): | ||
| lower = part.lower() | ||
| if lower in BRAND: | ||
| out.append(BRAND[lower]) | ||
| elif lower in ACRONYMS: | ||
| out.append(part.upper()) | ||
| else: | ||
| out.append(part.capitalize()) | ||
| return " ".join(out) |
There was a problem hiding this comment.
This logic is a duplicate of the label_for function defined earlier in the same file (lines 211-230). Additionally, the entire PYINNER block (lines 533-639) largely duplicates the logic found in scripts/splice-sdk-nav.py. Since this workflow already checks out the docs repository, it would be more maintainable to invoke the shared script directly rather than inlining a copy of the tree-building and label-formatting logic.
| _ACRONYMS = { | ||
| "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp", | ||
| "ipfs", "grpc", "http", "url", "json", "yaml", "xml", | ||
| "sql", "css", "html", "io", | ||
| } |
There was a problem hiding this comment.
Please include project-specific acronyms like hce, pdie, and dtsop in this list to ensure they are rendered in all-caps in the sidebar groups for Python and Rust.
| _ACRONYMS = { | |
| "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp", | |
| "ipfs", "grpc", "http", "url", "json", "yaml", "xml", | |
| "sql", "css", "html", "io", | |
| } | |
| _ACRONYMS = { | |
| "ai", "cli", "dsa", "tui", "api", "sdk", "ui", "mcp", | |
| "ipfs", "grpc", "http", "url", "json", "yaml", "xml", | |
| "sql", "css", "html", "io", "hce", "pdie", "dtsop", "rpc", | |
| } |
| def label_for(name: str) -> str: | ||
| """Format a dir name like `resq-dsa` into a sidebar label like | ||
| `ResQ DSA`. Acronyms upper-case, the brand `resq` rendered as | ||
| `ResQ`, everything else title-case. Hyphens become spaces. | ||
|
|
||
| Dotted names (e.g. `.NET`-style `ResQ.Blockchain`) are passed | ||
| through verbatim — they already carry their canonical casing | ||
| and segmenting by hyphen would corrupt them.""" | ||
| if "." in name: | ||
| return name | ||
| out: list[str] = [] | ||
| for part in name.split("-"): | ||
| lower = part.lower() | ||
| if lower in _BRAND: | ||
| out.append(_BRAND[lower]) | ||
| elif lower in _ACRONYMS: | ||
| out.append(part.upper()) | ||
| else: | ||
| out.append(part.capitalize()) | ||
| return " ".join(out) |
There was a problem hiding this comment.
As noted in the workflow template, this function should handle underscores to support snake_case directory names (common in Python) and should refine the dot heuristic to allow polishing of lowercase dotted names (common in TypeScript).
| def label_for(name: str) -> str: | |
| """Format a dir name like `resq-dsa` into a sidebar label like | |
| `ResQ DSA`. Acronyms upper-case, the brand `resq` rendered as | |
| `ResQ`, everything else title-case. Hyphens become spaces. | |
| Dotted names (e.g. `.NET`-style `ResQ.Blockchain`) are passed | |
| through verbatim — they already carry their canonical casing | |
| and segmenting by hyphen would corrupt them.""" | |
| if "." in name: | |
| return name | |
| out: list[str] = [] | |
| for part in name.split("-"): | |
| lower = part.lower() | |
| if lower in _BRAND: | |
| out.append(_BRAND[lower]) | |
| elif lower in _ACRONYMS: | |
| out.append(part.upper()) | |
| else: | |
| out.append(part.capitalize()) | |
| return " ".join(out) | |
| def label_for(name: str) -> str: | |
| """Format a dir name like `resq-dsa` or `count_min` into a sidebar label | |
| like `ResQ DSA` or `Count Min`. Acronyms upper-case, the brand `resq` | |
| rendered as `ResQ`, everything else title-case. Hyphens and underscores | |
| become spaces. | |
| Dotted names with mixed casing (e.g. `.NET`-style `ResQ.Blockchain`) | |
| are passed through verbatim.""" | |
| if "." in name and not name.islower(): | |
| return name | |
| out: list[str] = [] | |
| for part in name.replace("_", "-").split("-"): | |
| lower = part.lower() | |
| if lower in _BRAND: | |
| out.append(_BRAND[lower]) | |
| elif lower in _ACRONYMS: | |
| out.append(part.upper()) | |
| else: | |
| out.append(part.capitalize()) | |
| return " ".join(out) |
2 participants
Symptom (from your screenshot)
Rust sidebar mixed two label styles:
Fix
Add a smart label formatter:
Applied in:
Result
Live `docs.json` re-spliced; six Rust stub pages got `sidebarTitle` frontmatter so the live nav reflects the labels immediately.