feat(docs): version-stamp generated SDK READMEs#41
Conversation
Each language template now reads the package version at generation time (pyproject.toml for Python, .csproj <Version>/<VersionPrefix> for .NET, package.json for TypeScript) and stamps it into the top-level README.mdx alongside the workflow ref. Result: a user browsing the rendered docs can tell which release the reference describes without checking git history. Tag-triggered runs identify themselves clearly; main-triggered runs show `main`. This is the lightweight half of versioned SDK docs. Full multi-version support (parallel docs trees per release) is deferred until there's a v2 to document — the maintenance overhead of duplicating the nav isn't justified at v1.x.
|
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 (3)
✨ 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 updates the .NET, Python, and TypeScript API documentation workflows to include package versions and source references in the generated README files. The changes replace shell-based logic with Python scripts for more robust metadata extraction. Feedback includes improving regex patterns for parsing project files, handling 'unknown' version strings more cleanly by omitting the 'v' prefix, and ensuring source links correctly resolve to package directories within the monorepo.
| return "unknown" | ||
| text = candidates[0].read_text(encoding="utf-8") | ||
| for tag in ("Version", "VersionPrefix"): | ||
| m = re.search(rf"<{tag}>([^<]+)</{tag}>", text) |
There was a problem hiding this comment.
The regex for parsing .csproj tags is a bit fragile as it doesn't account for potential XML attributes on the tag (e.g., ). Using a more robust pattern would ensure the version is captured even in more complex project files.
m = re.search(rf"<{tag}\\b[^>]*>([^<]+)</{tag}>", text)| if not (output_dir / proj).is_dir(): | ||
| continue | ||
| version = read_version(proj) | ||
| print(f"- `{proj}` — `v{version}`") |
There was a problem hiding this comment.
When the version cannot be determined, the current implementation outputs vunknown. It would be cleaner to omit the v prefix in the fallback case.
v_str = f"v{version}" if version != "unknown" else version
print(f"- {proj} — {v_str}")| if not pyproject.exists(): | ||
| return "unknown" | ||
| text = pyproject.read_text(encoding="utf-8") | ||
| m = re.search(r'^\s*version\s*=\s*"([^"]+)"', text, re.M) |
There was a problem hiding this comment.
The regex for pyproject.toml only matches double-quoted version strings. TOML allows single quotes as well. Updating the regex to handle both will make the version extraction more reliable.
m = re.search(r'^\\s*version\\s*=\\s*["\']([^"\']+)["\']', text, re.M)| if not (output_dir / pkg_dir).is_dir(): | ||
| continue | ||
| version = read_version(pkg_dir) | ||
| print(f"- `{pkg_dir}` — `v{version}`") |
There was a problem hiding this comment.
Similar to the .NET template, this will output vunknown if the version lookup fails. It's better to avoid the prefix for the fallback value.
v_str = f"v{version}" if version != "unknown" else version
print(f"- {pkg_dir} — {v_str}")| banner = ( | ||
| f"> **Version:** `v{version}` · **Ref:** `{ref_name}` · " | ||
| f"**Source:** [`{repo}`](https://github.com/{repo})\n\n" | ||
| ) | ||
| # Insert banner after the first H1 (typedoc emits `# ui` | ||
| # or similar). If there's no leading H1, prepend. | ||
| h1_match = re.match(r'(# [^\n]+\n+)', text) | ||
| if h1_match: | ||
| text = text[:h1_match.end()] + banner + text[h1_match.end():] | ||
| else: | ||
| text = banner + text |
There was a problem hiding this comment.
There are three improvements possible here:
- Avoid the vunknown string when the version is missing.
- Use re.search with the MULTILINE flag instead of re.match for robustness against frontmatter.
- Ensure the Source link includes the relative path to the package directory to correctly resolve file locations in this monorepo.
v_display = f"v{version}" if version != "unknown" else version
banner = (
f"**Version:** {v_display} · **Ref:** {ref_name} · "
f"**Source:** [{repo}](https://github.com/{repo}/tree/{ref_name}/{pkg_dir})\\n\\n"
)
h1_match = re.search(r"(^# [^\\n]+\\n+)", text, re.M)
if h1_match:
text = text[:h1_match.end()] + banner + text[h1_match.end():]
else:
text = banner + textReferences
- When configuring source code links in documentation generators for monorepos, the base URL must include the relative path to the package directory to ensure 'View source' links resolve correctly to the file locations.
2 participants
Summary
Each language template now reads the package version at generation time and stamps it into the top-level `README.mdx` alongside the workflow ref.
Result: a user browsing the rendered docs can tell which release the reference describes without checking git history. Tag-triggered runs identify themselves clearly; main-triggered runs show `main`.
Why not full versioned docs?
This is the lightweight half of versioned SDK docs. Full multi-version support (parallel docs trees per release) is deferred until there's a v2 to document — the maintenance overhead of duplicating the nav for every version isn't justified at v1.x. When that day comes, the version stamps make it straightforward to migrate `sdks//api/` → `sdks//api/v1/` per language.
Test plan