Skip to content

Integrate GitHub README as Sphinx landing page with custom extension - #64

Merged
jpjarnoux merged 2 commits into
devfrom
docs/readme_duplicate
Oct 7, 2026
Merged

jpjarnoux merged 2 commits into
devfrom
docs/readme_duplicate

Conversation

@jpjarnoux

@jpjarnoux jpjarnoux commented Oct 6, 2026 •

Copy link
Copy Markdown
Member

Description

GitHub format and Sphinx format are not fully compatible. As the README is used in both the GitHub main page and the documentation first page, one or the other was badly formatted. In this PR I intend to fix it without duplicating file by writing a custom script called in the documentation building.

What changed

  • Added a custom Sphinx extension github_readme to parse GitHub README syntax into MyST format.
  • Updated documentation to use GitHub-flavored Markdown features (colon_fence, linkify, tasklist, etc.).
  • Modified README.md to incorporate GitHub alert syntax.
  • Added unit tests for README parsing and custom extension validation.
  • Updated pyproject.toml to include linkify-it-py dependency.
  • Updated developer documentation to explain the change and give guidelines.

Testing

A new unitary script works as a first cheap barrier. It's fast and doesn't need Sphinx or the test dataset. If someone adds MyST syntax to the README, CI fails and shows the line, before it reaches GitHub.

Rendering was tested both locally and directly into ReadTheDocs.

Documentation

  • Added/updated code comments
  • Added/updated docstring
  • Updated README or docs if needed
  • Added example usage (if relevant)

Checklist

  • My code follows the project guidelines
  • Complex logic is commented
  • No unnecessary files or debug code included
  • My PR is targeting the dev branch

## Changes:
- Added a custom Sphinx extension `github_readme` to parse GitHub README syntax into MyST format.
- Updated documentation to use GitHub-flavored Markdown features (`colon_fence`, `linkify`, `tasklist`, etc.).
- Modified `README.md` to incorporate GitHub alert syntax.
- Added unit tests for README parsing and custom extension validation.
- Updated `pyproject.toml` to include `linkify-it-py` dependency.
@jpjarnoux
jpjarnoux merged commit 93221b2 into dev Oct 7, 2026
5 checks passed
@jpjarnoux
jpjarnoux deleted the docs/readme_duplicate branch October 7, 2026 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants