docs: migrate README.rst to README.md and switch Sphinx to MyST parser - #477
Conversation
Convert the README from reStructuredText to Markdown with a 1:1 content match. Update pyproject.toml to point to README.md for PyPI. README.rst is kept for the Sphinx documentation build.
✅ Deploy Preview for commit-check ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughAdds a complete ChangesProject documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
github-actions
Bot
added
chore
documentation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #477 +/- ##
==========================================
+ Coverage 97.17% 97.26% +0.08%
==========================================
Files 12 12
Lines 1168 1168
==========================================
+ Hits 1135 1136 +1
+ Misses 33 32 -1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Merging this PR will improve performance by ×2.3
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ⚡ | test_empty_message_passes |
1,709.8 µs | 747.5 µs | ×2.3 |
Tip
Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.
Comparing chore/convert-readme-to-md (4abfdf7) with main (e98e907)
Footnotes
-
114 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
Improvements over plain Markdown conversion: - Use > [!TIP] / > [!NOTE] GFM alert syntax instead of plain blockquote - Use [^1] footnote syntax instead of HTML <sup>/<b id> backlinks
![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
🤖 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 `@README.md`:
- Around line 333-347: Update the return-value schema code block in README.md to
use a non-executable text/schema fence or valid placeholder strings such as
"<pass|fail>" for both top-level and per-check status fields; preserve the
documented schema structure and other placeholders.
- Around line 177-186: In the README section containing the pre-commit
configuration example, add an opening YAML code fence immediately before the “In
pre-commit hooks (.pre-commit-config.yaml)” comment, matching the existing
closing fence so subsequent documentation renders outside the block.
🪄 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 Plus
Run ID: 53b9ea77-bbe8-4457-beac-50b48e86ae08
📒 Files selected for processing (2)
README.mdpyproject.toml
| # In pre-commit hooks (.pre-commit-config.yaml) | ||
| repos: | ||
| - repo: https://github.com/commit-check/commit-check | ||
| rev: v2.11.1 | ||
| hooks: | ||
| - id: check-message | ||
| args: | ||
| - --subject-imperative=false | ||
| - --subject-max-length=100 | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Add the missing YAML fence.
Line 177 starts a pre-commit configuration example without opening a code block, while Line 186 closes one. This leaves the example unformatted and causes the following configuration documentation to render inside the wrong fenced block.
Proposed fix
-# In pre-commit hooks (.pre-commit-config.yaml)
+```yaml
+# In pre-commit hooks (.pre-commit-config.yaml)
repos:
- repo: https://github.com/commit-check/commit-check
...📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # In pre-commit hooks (.pre-commit-config.yaml) | |
| repos: | |
| - repo: https://github.com/commit-check/commit-check | |
| rev: v2.11.1 | |
| hooks: | |
| - id: check-message | |
| args: | |
| - --subject-imperative=false | |
| - --subject-max-length=100 | |
| ``` |
🤖 Prompt for 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.
In `@README.md` around lines 177 - 186, In the README section containing the
pre-commit configuration example, add an opening YAML code fence immediately
before the “In pre-commit hooks (.pre-commit-config.yaml)” comment, matching the
existing closing fence so subsequent documentation renders outside the block.
| ```python | ||
| { | ||
| "status": "pass" | "fail", | ||
| "checks": [ | ||
| { | ||
| "check": "<rule name>", | ||
| "status": "pass" | "fail", | ||
| "value": "<actual value that was checked>", | ||
| "error": "<human-readable error description>", | ||
| "suggest": "<how to fix>", | ||
| }, | ||
| # ... one entry per active rule | ||
| ] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the return-value schema non-executable or valid Python.
The python code block uses "pass" | "fail", which raises TypeError if copied and executed. Use a text/schema block or represent the alternatives as placeholder strings.
Proposed fix
-```python
+```text
{
- "status": "pass" | "fail",
+ "status": "<pass|fail>",
...
- "status": "pass" | "fail",
+ "status": "<pass|fail>",
...
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```python | |
| { | |
| "status": "pass" | "fail", | |
| "checks": [ | |
| { | |
| "check": "<rule name>", | |
| "status": "pass" | "fail", | |
| "value": "<actual value that was checked>", | |
| "error": "<human-readable error description>", | |
| "suggest": "<how to fix>", | |
| }, | |
| # ... one entry per active rule | |
| ] | |
| } | |
| ``` |
🤖 Prompt for 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.
In `@README.md` around lines 333 - 347, Update the return-value schema code block
in README.md to use a non-executable text/schema fence or valid placeholder
strings such as "<pass|fail>" for both top-level and per-check status fields;
preserve the documented schema structure and other placeholders.
- Add myst-parser to docs dependencies (pyproject.toml)
- Add myst_parser extension and .md source suffix to conf.py
- Convert docs/index.rst -> docs/index.md (MyST Markdown)
- Replace .. include:: with {include} MyST directive
- Set myst_all_links_external = True to suppress TOC anchor warnings
- Delete README.rst (replaced by README.md)
The Sphinx docs now build entirely from Markdown source files.
All existing .rst documentation pages remain unchanged.
|
shenxianpeng
changed the title
1 participant
Summary
Convert the project's documentation pipeline from reStructuredText to Markdown:
docs/index.rstwithdocs/index.md(MyST format), addedmyst-parserso Sphinx can build from Markdown sourcesChanges
README.mdREADME.rstdocs/index.md{include}directive pulls in README.mddocs/index.rstdocs/conf.pymyst_parserextension,.mdsource suffix,myst_all_links_external = Truepyproject.tomlreadme = "README.md", addedmyst-parserto docs depsuv.lockGFM features used
> [!TIP]/> [!NOTE]— GitHub alert syntax (replaces.. tip::)[^1]footnotes — GFM footnote syntax (replaces[#f1]_+ HTML backlinks)[^n]inline markers (replaces.. list-table::)Build verification
sphinx-build -b html— 0 warnings, 0 errors (MyST parser handles the Markdown README correctly)pytest— 430/430 pass (1 deselected pre-existing unrelated failure)ruff,mypy,codespell— all pass