improve(docs): clearer Python API list links + cleaner C++ tables#51
improve(docs): clearer Python API list links + cleaner C++ tables#51WomB0ComB0 merged 1 commit intomainfrom
Conversation
Two visual improvements identified by browsing the rendered output:
1. Python `<package>/overview.md` API list — drop backticks from
link text. The earlier `[\`Settings\`](url)` form rendered as
`<a><code>Settings</code></a>`, where the `<code>` background
visually masked the link styling and made the entries look like
inert code spans rather than clickable cross-references. Plain
`[Settings](url)` gets Mintlify's standard link underline +
accent color, signalling clickability at a glance. Unlinked
entries (re-exports without a documented home) keep the
code-span style so missing-target cases stay visually distinct.
2. C++ tables — strip moxygen's `\`inline\`` annotation. Doxygen
tags every header-defined method with `inline` (a compilation
directive, not API surface), and moxygen renders it on
practically every row of every class summary table. `const`,
`static`, `noexcept`, `virtual` are kept because they describe
observable behavior; only `inline` is filtered.
Templates updated so future regenerations stay correct; live files
under `sdks/{python,cpp}/api/` rewritten in-place to match.
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR systematically removes ChangesDocumentation inline qualifier removal
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 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 |
![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 refines the API documentation generation by stripping inline annotations from C++ headers and removing backticks from linked identifiers in Python documentation to improve visual styling. Feedback indicates that the sed command used to remove inline is too broad and may inadvertently affect descriptive text; a more restrictive regex is suggested. Furthermore, removing backticks from Python identifiers with underscores can cause Markdown rendering issues, such as unintended italics, necessitating the escaping of underscores in those names.
| working-directory: ${{ env.OUTPUT_DIR }} | ||
| run: | | ||
| find . -type f -name '*.md' -print0 | while IFS= read -r -d '' f; do | ||
| sed -i -E 's/ `inline`//g' "$f" |
There was a problem hiding this comment.
The global sed replacement is too aggressive and violates the general rule regarding MDX safety and CommonMark parsing. Because it performs a simple string replacement on the entire file, it will incorrectly strip the word 'inline' (when inside backticks) from function descriptions or prose (e.g., 'This method is inline for performance'), leading to corrupted documentation.
It is safer to restrict the replacement to contexts where it is clearly a modifier, such as when it is followed by another backticked modifier, a table cell separator (|), or the end of a line.
sed -i -E 's/ \x60inline\x60([[:space:]]*(\x60[^\x60]+\x60|[|]|$))/\1/g' "$f"References
- When processing Markdown/MDX files to escape curly braces for JSX compatibility, ensure the logic ignores content within inline code spans (backticks) to prevent breaking code snippets.
| # code spans elsewhere on the page. | ||
| api_lines.append( | ||
| f"- [`{name}`](./{target_rel}#{slug})" | ||
| f"- [{name}](./{target_rel}#{slug})" |
There was a problem hiding this comment.
Removing backticks from the link text introduces a regression for Python identifiers containing underscores (e.g., rabin_karp). In Markdown, underscores are interpreted as emphasis markers. Without backticks or explicit escaping, these links will render with unintended italics.
You should escape underscores in the name variable before appending it to the link text.
f"- [{name.replace('_', r'\\_')}](./{target_rel}#{slug})"2 participants
Summary
Two visual improvements identified by capturing screenshots of the rendered output with @elysiumoss/ui-capture.
1. Python overview API list — drop backticks from link text
Before:
```md
```
Renders as: `
Settings` — the `` background masks the link styling. Entries look like inert code spans, not clickable cross-references.After:
```md
```
Renders as: standard link with Mintlify's underline + accent color. Clickability is obvious at a glance.
Unlinked entries (`- `name`` for re-exports without a documented target) keep the code-span style so the missing-target case stays visually distinct.
2. C++ tables — strip moxygen's `\`inline\`` annotation
Doxygen tags every header-defined method with `inline` (a compilation directive, not API surface). moxygen renders it on practically every row of every class summary table — pure noise.
Before:
```md
| `bool` | `is_ok` `const` `inline` | Check if result is successful. |
```
After:
```md
| `bool` | `is_ok` `const` | Check if result is successful. |
```
`const`, `static`, `noexcept`, `virtual` are kept because they describe observable behavior. Only `inline` is stripped.
Files changed
Test plan
Summary by CodeRabbit
inlinequalifiers from displayed signatures in tables and method headings, while maintaining consistency with actual code implementations.