fix(rust-docs): hierarchical splice so library crates collapse properly#66
fix(rust-docs): hierarchical splice so library crates collapse properly#66WomB0ComB0 merged 1 commit intomainfrom
Conversation
The Rust template's splice was the original flat version: every entry from _pages.json mapped to a standalone PAGE registration under the language group. This worked when every crate was a single stub page (PR #49 era), but PR #62 introduced multi-file output for library crates (resq-dsa with bloom.md, count_min.md, graph.md, ...). The flat splice rendered all those module pages as direct siblings of the language group rather than collapsing them into a `resq-dsa` group. Visible symptom: clicking `Resq dsa` in the sidebar showed only the index page; the per-module pages were registered but not discoverable from the nav (the user had to type each URL by hand or hope for autocomplete). The right-side TOC showed module structure but the left sidebar was flat. Replace with the hierarchical-with-landing splice from PR #61 (used by TS / .NET / Python / C++): each top-level dir under sdks/rust/api/ becomes a collapsible group with its index.md as the landing, and per-module pages as children. Single-file stub crates (binary-only TUIs) stay as leaf PAGEs. Local docs.json re-spliced with `scripts/splice-sdk-nav.py` so main reflects the corrected structure immediately. Verified Rust nav structure: 1 README + 6 leaf PAGEs (binary-only) + 5 GROUPs (library crates with rustdoc API)
|
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 (2)
✨ 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 |
github-actions
Bot
added
area:content
![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 updates the Rust API documentation generation process to create a hierarchical sidebar structure in Mintlify instead of a flat list. This is achieved by implementing a tree-building algorithm in the GitHub Actions workflow that groups library crates and submodules. Feedback was provided to refine the to_mintlify function to prevent duplicate sidebar entries by merging files that serve as landing pages for subdirectories into their respective groups.
| def to_mintlify(node, group_name): | ||
| pages = [] | ||
| if "_landing" in node: | ||
| pages.append(node["_landing"]) | ||
| for fname, full_id in sorted(node.get("_files", [])): | ||
| pages.append(full_id) | ||
| for dname, sub in sorted(node.get("_dirs", {}).items()): | ||
| pages.append(to_mintlify(sub, dname)) | ||
| return pages if group_name is None else {"group": group_name, "pages": pages} |
There was a problem hiding this comment.
The current logic results in duplicate entries in the sidebar when a module (e.g., commands) has both a documentation file and a subdirectory for submodules. This happens because the file is added to the parent's _files list while the subdirectory becomes a separate group.
We should detect when a file name matches a subdirectory name and use that file as the landing page for the group to provide a cleaner navigation experience and ensure the output adheres to the Mintlify nested group structure.
def to_mintlify(node, group_name):
pages = []
if "_landing" in node:
pages.append(node["_landing"])
files = {fname: full_id for fname, full_id in node.get("_files", [])}
dirs = node.get("_dirs", {})
# Merge files that act as landing pages for subdirectories
for dname, sub in dirs.items():
if dname in files:
sub["_landing"] = files.pop(dname)
for fname in sorted(files):
pages.append(files[fname])
for dname, sub in sorted(dirs.items()):
pages.append(to_mintlify(sub, dname))
return pages if group_name is None else {"group": group_name, "pages": pages}References
- In Mintlify docs.json navigation configuration, use a nested group object to define custom sidebar labels for pages, as the schema does not support a label property within the pages array.
2 participants
Symptom (from your screenshot)
Clicking `Resq dsa` in the sidebar showed the resq-dsa index content but the left sidebar was flat — no collapsible group, no `bloom`/`count_min`/`graph`/`heap`/`trie` sub-entries. The right-side TOC showed module structure (because the page itself rendered fine), but you couldn't navigate to per-module pages from the nav.
Root cause
The Rust template's splice was the original flat-list version from PR #49: every entry from `_pages.json` mapped to a standalone PAGE registration. That worked when every crate was a single stub page. PR #62 introduced multi-file output for library crates (resq-dsa with `bloom.md`, `count_min.md`, `graph.md`, ...) but the splice still flattened them.
Fix
Replace with the hierarchical-with-landing splice from PR #61 (already in use by TS / .NET / Python / C++). Each top-level dir under `sdks/rust/api/` becomes a collapsible group with its `index.md` as the landing, and per-module pages as children. Single-file stub crates (binary-only TUIs) stay as leaf PAGEs.
Verified structure