feat(rust-docs): render source README on each crate's landing page#68
Conversation
cargo-doc-md generated each library crate's index.md from the
lib.rs //! doc comment — accurate but plain (no diagrams, no
badges, no install instructions). The source README.md in each
crate has the rich content: mermaid architecture diagrams,
crates.io/docs.rs/license badges, install snippets, examples.
Previously that content was only embedded in binary-only stubs;
library crates dropped it on the floor.
Replace each library crate's auto-generated index.md with a
hybrid landing:
1. version + license banner
2. cleaned README.md from the source repo (mermaid diagrams,
badges, install instructions, prose — full fidelity)
3. ## Modules section linking to each cargo-doc-md per-module
page
The original cargo-doc-md index.md content is dropped because
the README provides the same information more richly, and the
per-module pages keep the full API surface (types, traits,
functions, methods) intact.
Crates without a README.md (e.g. resq-ai) gracefully fall through
to banner + Modules section only.
Live sdks/rust/api/resq-{ai,bin,cli,dsa,tui}/index.md rebuilt
locally so the change shows up immediately when pulled. Future
regenerations stay correct via the updated template.
|
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 (1)
📝 WalkthroughWalkthroughThe PR overhauls Rust API documentation across six crates by introducing a landing page generation workflow that assembles hybrid index pages combining version/license banners, cleaned README content with GitHub blob link rewriting, and auto-generated module listings. Five crate documentation pages are expanded from minimal stubs or briefly-organized reference material into comprehensive guides with architecture diagrams, detailed command/module/function reference, usage examples, and configuration documentation. ChangesAPI Documentation Expansion and Landing Page Generation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
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 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.
Actionable comments posted: 1
🤖 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.
Inline comments:
In `@sdks/rust/api/resq-cli/index.md`:
- Line 214: The MDX build fails because the unescaped "<" in the bucket
description "low (<1 MB)" is parsed as JSX; update the source text that
generates sdks/rust/api/resq-cli/index.md (the sentence containing "Fetches
package sizes... high (>10 MB), medium (1-10 MB), and low (<1 MB) buckets") to
escape the angle bracket (replace "<1 MB" with "<1 MB") or rephrase (e.g.,
"less than 1 MB") in the README.md in crates/resq-cli or the generator source so
the produced index.md no longer contains an unescaped "<".
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a46783fa-1963-45a8-9170-905a6ba2ce5d
📒 Files selected for processing (6)
automation/source-repo-templates/api-docs.rust.ymlsdks/rust/api/resq-ai/index.mdsdks/rust/api/resq-bin/index.mdsdks/rust/api/resq-cli/index.mdsdks/rust/api/resq-dsa/index.mdsdks/rust/api/resq-tui/index.md
The local rebuild of the lib crate index.md files skipped the template's MDX-escape pass, leaving prose like `(<1 MB)` in resq-cli's README to trip the broken-links check (the parser treats <1 as the start of a JSX tag with a digit-prefixed name). Run the same backtick-aware escape walker over the new files.
![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 hybrid landing pages by combining version banners, crate README content, and module links. Feedback indicates that the generated module links are missing the required .md extensions, which will break navigation. Furthermore, for crates without a README, the new logic results in a loss of descriptive content; a fallback to the Cargo.toml description was suggested to maintain documentation quality.
| module_lines = [ | ||
| f"- [`{p.stem}`](./{p.stem})" | ||
| for p in module_files | ||
| ] |
There was a problem hiding this comment.
The generated links for modules are missing the .md extension. Since the files on disk retain the .md suffix (as seen in the filtering logic at line 279), these links will likely fail to resolve in the documentation site. Additionally, the post-processing script that prefixes relative links (lines 371-408) specifically looks for the .md extension, so these links will be skipped by that safety check as well.
module_lines = [
f"- [{p.stem}](./{p.name})"
for p in module_files
]| body_parts = [f"# {meta['name']}", "", banner_for(meta).rstrip(), ""] | ||
| if readme.is_file(): | ||
| body = readme.read_text(encoding="utf-8") | ||
| body = re.sub(r"^\s*<!--.*?-->\s*", "", body, count=1, flags=re.S) | ||
| body = re.sub(r"^#\s+[^\n]+\n+", "", body, count=1) | ||
| body = rewrite_relative_links(body, crate_dir) | ||
| body_parts.extend([body.rstrip(), ""]) |
There was a problem hiding this comment.
For crates without a README.md (such as resq-ai), this change results in a landing page that lacks any description of the crate's purpose, losing information that was previously extracted from the lib.rs doc comments. To maintain documentation quality, consider falling back to the description field from Cargo.toml when the README is missing, similar to the logic used for binary stubs at line 336.
body_parts = [f"# {meta['name']}", "", banner_for(meta).rstrip(), ""]
if readme.is_file():
body = readme.read_text(encoding="utf-8")
body = re.sub(r"^\s*<!--.*?-->\s*", "", body, count=1, flags=re.S)
body = re.sub(r"^#\s+[^\n]+\n+", "", body, count=1)
body = rewrite_relative_links(body, crate_dir)
body_parts.extend([body.rstrip(), ""])
elif meta["description"]:
body_parts.extend([meta["description"], ""])2 participants
Summary
Per request: keep the rich README rendering (mermaid diagrams, badges, install instructions) on each library crate's landing page, then list per-module API pages below.
Before
Each library crate's `index.md` was `cargo-doc-md`'s output — derived from the `lib.rs` `//!` doc comment. Accurate but plain: no diagrams, no badges, no install instructions. The mermaid architecture / install / examples in each crate's source `README.md` were ignored for library crates (only used for binary-only stubs).
After
Each library crate's `index.md` is now a hybrid landing:
Per-module pages (`bloom.md`, `count_min.md`, etc.) untouched — full rustdoc API surface preserved. Crates without a `README.md` (e.g. `resq-ai`) gracefully fall through to banner + Modules section only.
Live state
`sdks/rust/api/resq-{ai,bin,cli,dsa,tui}/index.md` rebuilt locally so the change is visible immediately on pull, no workflow regen needed:
Test plan
Summary by CodeRabbit