docs: Convert github alerts to sphinx admonitions #1483
Conversation
Adds a sphinx extension to automatically convert github markdown style alerts to sphinx admonitions during the sphinx build process. This means that `> [!NOTE]`, `> [!WARNING]` etc. will render appropriately in GitHub and on docs.nvidia.com Signed-off-by: Neal Vaidya <[email protected]>
nealvaidya
requested review from
nnshah1,
tanmayv25,
piotrm-nvidia,
ptarasiewiczNV,
ryanolson,
grahamking,
paulhendricks,
biswapanda,
tmonty12,
GuanLuo,
rmccorm4,
tedzhouhk,
alec-flowers,
kkranen,
jthomson04,
ishandhanani,
PeaBrane and
a team
as code owners
WalkthroughA new custom Sphinx extension for converting GitHub-style markdown alert blockquotes into MyST admonitions has been introduced. The extension is registered in the documentation build configuration, and supporting module metadata is added. The documentation build process is updated to recognize and utilize this new extension. Changes
Sequence Diagram(s)sequenceDiagram
participant Sphinx
participant GitHubAlertsTransformer
participant Document
Sphinx->>GitHubAlertsTransformer: On 'doctree-resolved' event (for markdown files)
GitHubAlertsTransformer->>Document: Scan for GitHub alert blockquotes
GitHubAlertsTransformer->>Document: Replace blockquotes with MyST admonition nodes
GitHubAlertsTransformer-->>Sphinx: Transformation complete
Poem
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![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
🧹 Nitpick comments (1)
docs/_extensions/github_alerts.py (1)
234-234: Consider removing or documenting the unusedgithub_alerts_mappingconfig.The
github_alerts_mappingconfiguration value is added but never used in the implementation. If it's intended for future use, consider adding a comment explaining its purpose. Otherwise, it should be removed to avoid confusion.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/_extensions/__init__.py(1 hunks)docs/_extensions/github_alerts.py(1 hunks)docs/conf.py(3 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Build and Test - vllm
🔇 Additional comments (3)
docs/_extensions/__init__.py (1)
1-19: LGTM! Clean module initialization.The package structure is well-organized with proper licensing header and clear module documentation.
docs/conf.py (1)
28-28: Configuration changes look good.The modifications correctly set up the custom extension by:
- Adding the
_extensionsdirectory to the Python path- Registering the
github_alertsextensionThe use of
sys.path.insert(0, ...)ensures custom extensions take precedence.Also applies to: 38-38, 85-85
docs/_extensions/github_alerts.py (1)
1-246: Well-structured Sphinx extension with comprehensive functionality.The extension follows Sphinx best practices with proper event handling, configuration management, and error handling. The AST-based approach for transforming GitHub alerts is robust and maintainable.
- Use classes in maps instead of instances - remove unused config map Signed-off-by: Neal Vaidya <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/_extensions/github_alerts.py(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Build and Test - vllm
🔇 Additional comments (1)
docs/_extensions/github_alerts.py (1)
42-52: Good fix:ALERT_MAPPINGnow stores classes, not instancesChanging the mapping to use node classes eliminates the shared-instance problem highlighted in the earlier review. Nice job.
Signed-off-by: Neal Vaidya <[email protected]>
Overview:
Adds a sphinx extension to automatically convert github markdown style alerts to sphinx admonitions during the sphinx build process. This means that
> [!NOTE],> [!WARNING]etc. will render appropriately in GitHub and on docs.nvidia.comSummary by CodeRabbit
New Features
Documentation