docs: upgrade README badges and add auto-sync to introduction.rst#250
Conversation
Upgrade README badge style to for-the-badge for a bolder, more modern look and add pypandoc-based sync script that auto-generates docs/source/introduction.rst from README.md, hooked into both the Makefile and CI workflow. Also update roadmap content. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
yuecideng
added
docs
There was a problem hiding this comment.
Pull request overview
This PR modernizes the project’s README badge styling and introduces an automated mechanism to keep the Sphinx docs introduction page synchronized with README.md, so the docs site reflects the latest project overview.
Changes:
- Updated README badges to
for-the-badgestyle (including Python logo on the Python badge). - Added
docs/scripts/sync_readme.pyto convertREADME.md→docs/source/introduction.rstvia pandoc + post-processing. - Wired the sync step into docs builds (Makefile) and CI, and refreshed roadmap wording.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Updates shields badges and tweaks intro wording to match current positioning. |
docs/scripts/sync_readme.py |
New README→RST conversion + Sphinx-specific cleanup logic. |
docs/source/introduction.rst |
Updated to match README content and new generation format. |
docs/Makefile |
Runs README→introduction sync automatically before Sphinx build targets. |
docs/requirements.txt |
Adds pandoc binary dependency for conversion. |
.github/workflows/main.yml |
Runs the sync step during docs build in CI. |
docs/source/resources/roadmap.md |
Roadmap copy updates reflecting current priorities. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| `CONTRIBUTING.md <CONTRIBUTING.md>`__ file in this repository for | ||
| guidelines on how to get started. |
There was a problem hiding this comment.
This hyperlink is currently relative (CONTRIBUTING.md) and will point to a non-existent page in the built documentation output (likely a 404). Use an absolute GitHub URL, or add CONTRIBUTING to the Sphinx source tree and link with :doc:/toctree so it resolves in the docs site.
| `CONTRIBUTING.md <CONTRIBUTING.md>`__ file in this repository for | |
| guidelines on how to get started. | |
| `CONTRIBUTING.md <https://github.com/DexForce/EmbodiChain/blob/main/CONTRIBUTING.md>`__ | |
| file in this repository for guidelines on how to get started. |
| if re.match(r"^\s+\[!NOTE\]", line): | ||
| note_match = re.match(r"^\s+\[!NOTE\]\s*(.*)", line) | ||
| note_text = note_match.group(1) if note_match else "" | ||
| note_text = note_text.replace("\\*", "*") | ||
| note_lines: list[str] = [] |
There was a problem hiding this comment.
The [!NOTE] conversion logic is producing malformed RST in the generated introduction.rst (the list markers end up inline with the preceding sentence). Update the NOTE post-processing to preserve list structure inside the directive (e.g., split wrapped/inlined * items onto their own lines and insert the required blank line before the list).
| EmbodiChain is in Alpha and under active development: * More | ||
| features will be continually added in the coming months. You can find | ||
| more details in the | ||
| `roadmap <https://dexforce.github.io/EmbodiChain/resources/roadmap.html>`__. | ||
| * Since this is an early release, we welcome feedback (bug reports, | ||
| feature requests, etc.) via GitHub Issues. |
There was a problem hiding this comment.
The generated NOTE admonition formatting is invalid reStructuredText: the bullet list items are being merged into the preceding sentence ("...development: * More ..."), which will render incorrectly and can trigger Sphinx warnings/errors (docs build uses -W). Regenerate this block so list items are on their own indented lines inside the directive (and typically separated from the introductory sentence by a blank line).
| EmbodiChain is in Alpha and under active development: * More | |
| features will be continually added in the coming months. You can find | |
| more details in the | |
| `roadmap <https://dexforce.github.io/EmbodiChain/resources/roadmap.html>`__. | |
| * Since this is an early release, we welcome feedback (bug reports, | |
| feature requests, etc.) via GitHub Issues. | |
| EmbodiChain is in Alpha and under active development. You can find | |
| more details in the | |
| `roadmap <https://dexforce.github.io/EmbodiChain/resources/roadmap.html>`__. | |
| * More features will be continually added in the coming months. | |
| * Since this is an early release, we welcome feedback (bug reports, | |
| feature requests, etc.) via GitHub Issues. |
Description
This PR upgrades the README badge style and adds automated synchronization between README.md and docs/source/introduction.rst.
Badge upgrades:
for-the-badgestyle (taller, bolder, more modern look)Auto-sync mechanism:
docs/scripts/sync_readme.pyconverts README.md → introduction.rst using pypandocdocs/Makefileso docs always build from the latest README.md.github/workflows/main.yml)--checkmode for CI staleness validationOther updates:
Dependencies:
pypandoc_binaryadded todocs/requirements.txtType of change
Screenshots
Badges before (default style) → after (
for-the-badgestyle):Before:
After:
Checklist
black .command to format the code base.🤖 Generated with Claude Code