Conversation
Reviewer's GuideThis PR refines the documentation style guide by enforcing GitHub-flavored Markdown with sequential numeric footnotes, converting existing reference-style links to numbered footnotes, and adding guidance for cross-document linking via GitHub kebab-case anchors. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Warning Rate limit exceeded@leynos has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 5 minutes and 19 seconds before requesting another review. ⌛ 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. 📒 Files selected for processing (1)
Summary by CodeRabbit
WalkthroughUpdate the documentation style guide to clarify Markdown and footnote conventions. Change footnote references to use numbered Markdown syntax, add guidance for linking to headings via GitHub anchors, and explicitly discourage non-standard citation formats. Revise footnote examples and update references to the NumPy docstring standard accordingly. Changes
Sequence Diagram(s)No sequence diagram necessary due to documentation-only changes. Estimated code review effort1 (~2 minutes) Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 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
CodeRabbit Configuration File (
|
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey @leynos - I've reviewed your changes and they look great!
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location> `docs/documentation-style-guide.md:37` </location>
<code_context>
- Ensure blank lines before and after bulleted lists and fenced blocks.
- Ensure tables have a delimiter line below the header row.
+- When linking to headings in other documents, use GitHub's kebab-case anchors.
+ For example, `docs/rust-binary-router-library-design.md#3-1-binary-serialization-libraries-in-rust`
+ links to "3.1. Binary Serialization Libraries in Rust".
</code_context>
<issue_to_address>
This example line exceeds 80 columns and should be wrapped.
Even example lines in bullets should be wrapped to 80 columns, unless they are code blocks or tables.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/documentation-style-guide.md(4 hunks)
🧰 Additional context used
📓 Path-based instructions (4)
docs/**/*.md
📄 CodeRabbit Inference Engine (docs/documentation-style-guide.md)
docs/**/*.md: Use British English based on the Oxford English Dictionary (en-oxendict) for documentation, except when US spelling is used in an API (e.g.,color), and spell the project licence file asLICENSE.
Use the Oxford comma in documentation.
Treat company names as collective nouns (e.g., 'Lille Industries are expanding') in documentation.
Write headings in sentence case in documentation.
Use Markdown headings (#,##,###, etc.) in order without skipping levels.
Follow markdownlint recommendations for Markdown files.
Provide code blocks and lists using standard Markdown syntax.
Always provide a language identifier for fenced code blocks in Markdown; useplaintextfor non-code text.
Use-as the first level bullet and renumber lists when items change in Markdown.
Prefer inline links using[text](url)or angle brackets around the URL in Markdown.
Ensure blank lines before and after bulleted lists and fenced code blocks in Markdown.
Ensure tables in Markdown have a delimiter line below the header row.
Expand any uncommon acronym on first use in documentation (e.g., Continuous Integration (CI)).
Wrap paragraphs at 80 columns in documentation.
Wrap code at 120 columns in documentation.
Do not wrap tables in documentation.
Use footnotes referenced with[^label]in documentation.
Include Mermaid diagrams in documentation where it adds clarity.
When embedding figures in documentation, useand provide concise alt text describing the content.
Add a short description before each Mermaid diagram in documentation so screen readers can understand it.The logging class diagram should be maintained in Markdown documentation using Mermaid syntax for clarity and up-to-date reference.
docs/**/*.md: Use the markdown files within the docs/ directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update the relevant file(s) in the docs/ directory to r...
Files:
docs/documentation-style-guide.md
**/*.md
📄 CodeRabbit Inference Engine (AGENTS.md)
**/*.md: For Markdown files (.md only): Run make markdownlint or use integrated editor linting.
For Markdown files (.md only): Validate Mermaid diagrams with make nixie.
Files:
docs/documentation-style-guide.md
⚙️ CodeRabbit Configuration File
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -our) spelling and grammar
- Paragraphs and bullets must be wrapped to 80 columns, except where a long URL would prevent this (in which case, silence MD013 for that line)
- Code blocks should be wrapped to 120 columns.
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
docs/documentation-style-guide.md
docs/**/*.{py,rs,md}
📄 CodeRabbit Inference Engine (docs/dev-workflow.md)
docs/**/*.{py,rs,md}: Runmake fmtto format Python, Rust, and Markdown sources
Runmake check-fmtto verify formatting of Python, Rust, and Markdown sources without modifying files
Files:
docs/documentation-style-guide.md
{README.md,docs/**}
📄 CodeRabbit Inference Engine (.rules/python-00.mdc)
Colocate documentation (README.md or docs/) near reusable packages and include usage examples
Files:
docs/documentation-style-guide.md
🔇 Additional comments (3)
docs/documentation-style-guide.md (3)
27-29: Adopt numeric footnotes correctly.Numeric reference
[^\d]is in place and the matching definition exists; this aligns with the new convention.
117-118: Footnote link updated correctly.The inline reference now uses the numbered footnote scheme and complies with the new rule set.
144-145: Footnote definitions match references.Footnote numbers are sequential and the URL is wrapped in angle brackets, fulfilling the documented requirements.
1 participant
Summary
Testing
make markdownlintmake nixiehttps://chatgpt.com/codex/tasks/task_e_687e7a1c30448322b53890c2b214ab9d
Summary by Sourcery
Update the documentation style guide to use GitHub-flavoured Markdown anchors and sequential numeric footnotes, replacing legacy reference-style links.
Documentation: