From 4e2d74681e640fad6793c2f682eee46df22322a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Arnoux?= <39793176+jpjarnoux@users.noreply.github.com> Date: Tue, 6 Oct 2026 13:37:31 +0200 Subject: [PATCH 1/2] Integrate GitHub README as Sphinx landing page with custom extension ## 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. --- README.md | 12 ++-- docs/_ext/github_readme.py | 108 ++++++++++++++++++++++++++++++++ docs/conf.py | 8 ++- pyproject.toml | 1 + tests/unit_tests/test_readme.py | 61 ++++++++++++++++++ 5 files changed, 182 insertions(+), 8 deletions(-) create mode 100644 docs/_ext/github_readme.py create mode 100644 tests/unit_tests/test_readme.py diff --git a/README.md b/README.md index a0c67d8..79a2741 100644 --- a/README.md +++ b/README.md @@ -57,10 +57,9 @@ In the following we will name this file *pangenomes.tsv* | ... | ... | | PangenomeX | path/to/pangenomeX | -```{note} -We recommend using an absolute path in this file to avoid errors. -You can use the path from your current directory or the path from the input file as a relative path to find pangenomes -``` +> [!NOTE] +> We recommend using an absolute path in this file to avoid errors. +> You can use the path from your current directory or the path from the input file as a relative path to find pangenomes ## Biological systems detection @@ -181,6 +180,5 @@ PANORAMA is still in early development. Have suggestions, ideas, or bug reports? 👉 [Open an issue on GitHub](https://github.com/labgem/PANORAMA/issues) -```{important} -We cannot correct bugs if we do not know about them and will try to help you the best we can -``` +> [!IMPORTANT] +> We cannot correct bugs if we do not know about them and will try to help you the best we can diff --git a/docs/_ext/github_readme.py b/docs/_ext/github_readme.py new file mode 100644 index 0000000..a7a1539 --- /dev/null +++ b/docs/_ext/github_readme.py @@ -0,0 +1,108 @@ +"""Sphinx extension to reuse the GitHub README as the documentation landing page. + +README.md is written for GitHub. When it is pulled into the docs with MyST's ``{include}`` +directive, this extension: + +- rewrites GitHub alerts (``> [!NOTE]``) into MyST admonitions; +- warns about MyST-only syntax, which GitHub would display as raw text. + +The other GitHub-flavored features (bare URL autolinks, strikethrough, task lists, mermaid +fences) are handled by MyST extensions enabled in ``conf.py``. + +This module must stay importable without Sphinx so the README can be checked by the test suite. +""" + +import re +from pathlib import Path + +README_NAME = "README.md" + +GITHUB_ALERT = re.compile( + r"^> \[!(?PNOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*\n(?P(?:^>.*(?:\n|$))*)", + flags=re.MULTILINE, +) + +FENCE = re.compile(r"^ {0,3}(?P`{3,}|~{3,}|:{3,})(?P.*)$") +# Scanned left to right, so a role written inside an inline code span is consumed as code +MYST_ROLE_OR_CODE = re.compile(r"(?P\{[\w:.+-]+\}`[^`]+`)|`+[^`]*`+") +MYST_INLINE_SYNTAX = { + "MyST target": re.compile(r"^\s*\([^()\s]+\)=\s*$"), + "MyST comment": re.compile(r"^\s*%"), + "MyST block break": re.compile(r"^\s*\+\+\+"), +} + + +def github_alerts_to_myst(text: str) -> str: + """Convert GitHub alert blockquotes into MyST colon-fence admonitions. + + Args: + text: Markdown content using GitHub alert syntax. + + Returns: + The same content with every alert replaced by a MyST admonition. + """ + + def _replace(match: re.Match) -> str: + body = re.sub(r"^> ?", "", match["body"], flags=re.MULTILINE).rstrip("\n") + return f":::{{{match['kind'].lower()}}}\n{body}\n:::\n" + + return GITHUB_ALERT.sub(_replace, text) + + +def find_myst_only_syntax(text: str) -> list[tuple[int, str]]: + """Find MyST syntax that GitHub cannot render. + + Content of regular code blocks is ignored, so documenting MyST syntax inside a code block is fine. + + Args: + text: Markdown content meant to be rendered by GitHub. + + Returns: + A list of ``(line_number, description)`` tuples, one per offending line (1-indexed). + """ + issues = [] + open_fence = None + for line_number, line in enumerate(text.splitlines(), start=1): + fence = FENCE.match(line) + if open_fence is not None: + if fence and fence["marker"][0] == open_fence[0] and len(fence["marker"]) >= len(open_fence): + if not fence["info"].strip(): + open_fence = None + continue + if fence: + marker, info = fence["marker"], fence["info"].strip() + if marker.startswith(":"): + issues.append((line_number, f"MyST colon fence '{line.strip()}'")) + elif info.startswith("{"): + issues.append((line_number, f"MyST directive '{line.strip()}'")) + open_fence = marker + continue + if any(match["role"] for match in MYST_ROLE_OR_CODE.finditer(line)): + issues.append((line_number, f"MyST role in '{line.strip()}'")) + for name, pattern in MYST_INLINE_SYNTAX.items(): + if pattern.match(line): + issues.append((line_number, f"{name} '{line.strip()}'")) + return issues + + +def convert_included_readme(app, relative_path: Path, parent_docname: str, content: list[str]) -> None: + """Sphinx ``include-read`` handler converting the included README from GitHub to MyST syntax.""" + if relative_path.name != README_NAME: + return + + from sphinx.util import logging + + logger = logging.getLogger(__name__) + for line_number, issue in find_myst_only_syntax(content[0]): + logger.warning( + "%s will not render on GitHub, use GitHub-flavored Markdown instead", + issue, + location=f"{(Path(app.srcdir) / relative_path).resolve()}:{line_number}", + ) + content[0] = github_alerts_to_myst(content[0]) + + +def setup(app): + """Register the extension in Sphinx.""" + app.connect("include-read", convert_included_readme) + return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/conf.py b/docs/conf.py index 21002f8..fdb479d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,6 +7,7 @@ # -- Imports ----------------------------------------------------------------- import datetime +import sys from pathlib import Path import myst_parser @@ -17,6 +18,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # +sys.path.insert(0, str(Path(__file__).resolve().parent / "_ext")) # -- Project information ----------------------------------------------------- @@ -52,9 +54,13 @@ "sphinxcontrib.jquery", "sphinxcontrib.mermaid", "sphinx_copybutton", + "github_readme", # Local extension (_ext/): renders the GitHub README as the landing page ] -myst_enable_extensions = ["colon_fence"] +# Besides colon_fence, these extensions mirror GitHub-flavored Markdown so README.md renders the same in both places +myst_enable_extensions = ["colon_fence", "linkify", "strikethrough", "tasklist"] +myst_fence_as_directive = ["mermaid"] +myst_linkify_fuzzy_links = False # Like GitHub, only autolink http(s):// and www. URLs, not "README.md" myst_heading_anchors = 4 source_suffix = {".md": "markdown", ".rst": "restructuredtext"} diff --git a/pyproject.toml b/pyproject.toml index 09a6e4e..c1c1936 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ doc = [ "readthedocs-sphinx-search>=0.3.2", "sphinx-autobuild>=2024.10.3", "myst-parser>=4.0.1", + "linkify-it-py>=2.0.3", # Required by the MyST "linkify" extension "docutils>=0.21.2", # Version 0.22.2 is not compatible with myst parser 4.0.1 "sphinxcontrib.mermaid>=1.0.0", "sphinxcontrib-jquery>=4.1", diff --git a/tests/unit_tests/test_readme.py b/tests/unit_tests/test_readme.py new file mode 100644 index 0000000..e57aa7d --- /dev/null +++ b/tests/unit_tests/test_readme.py @@ -0,0 +1,61 @@ +"""Tests for the README rendering on both GitHub and the Sphinx documentation.""" + +import importlib.util +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +README = ROOT / "README.md" + +_spec = importlib.util.spec_from_file_location("github_readme", ROOT / "docs" / "_ext" / "github_readme.py") +github_readme = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(github_readme) + + +def test_readme_has_no_myst_only_syntax(): + """README.md is rendered by GitHub, so it must only use GitHub-flavored Markdown.""" + issues = github_readme.find_myst_only_syntax(README.read_text(encoding="utf-8")) + assert not issues, "README.md uses MyST-only syntax:\n" + "\n".join( + f" line {line}: {issue}" for line, issue in issues + ) + + +@pytest.mark.parametrize("kind", ["NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"]) +def test_github_alert_to_myst(kind): + text = f"Before\n\n> [!{kind}]\n> First line\n>\n> Second line\n\nAfter\n" + expected = f"Before\n\n:::{{{kind.lower()}}}\nFirst line\n\nSecond line\n:::\n\nAfter\n" + assert github_readme.github_alerts_to_myst(text) == expected + + +def test_github_alert_keeps_code_block(): + text = "> [!TIP]\n> Run:\n> ```shell\n> panorama -h\n> ```\n" + expected = ":::{tip}\nRun:\n```shell\npanorama -h\n```\n:::\n" + assert github_readme.github_alerts_to_myst(text) == expected + + +def test_regular_blockquote_untouched(): + text = "> Just a quote\n> on two lines\n" + assert github_readme.github_alerts_to_myst(text) == text + + +@pytest.mark.parametrize( + "line", + [ + "```{note}", + ":::{warning}", + ":::", + "See {ref}`user/install:Installation`", + "(my-label)=", + "% a MyST comment", + "+++", + ], +) +def test_myst_only_syntax_detected(line): + issues = github_readme.find_myst_only_syntax(f"Intro\n\n{line}\n") + assert [number for number, _ in issues] == [3] + + +def test_myst_syntax_inside_code_block_ignored(): + text = "````markdown\n```{note}\nText\n```\n{ref}`a`\n````\n\nUse `{ref}` roles in the docs.\n" + assert github_readme.find_myst_only_syntax(text) == [] From 5500fc06e864c007b1b13f7c9f9be5671d5ba291 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Arnoux?= <39793176+jpjarnoux@users.noreply.github.com> Date: Tue, 6 Oct 2026 13:58:36 +0200 Subject: [PATCH 2/2] Document README integration details and maintain GitHub-flavored Markdown compatibility --- docs/developer/buildDoc.md | 46 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/developer/buildDoc.md b/docs/developer/buildDoc.md index c382dbb..95bed3c 100644 --- a/docs/developer/buildDoc.md +++ b/docs/developer/buildDoc.md @@ -73,6 +73,49 @@ docstrings and rebuild. **However**, if you add a new package or module, you'll need to regenerate the API docs. See the [Updating API documentation](#updating-api) section below. +(readme-doc)= + +### The README + +The [README](https://github.com/labgem/PANORAMA/blob/dev/README.md) is the landing page of the GitHub repository **and** of this documentation, which pulls it +in with an `{include}` directive in `docs/index.md`. One file, two renderers: GitHub only understands GitHub-flavored +Markdown, while Sphinx reads MyST. To keep a single file, **write the README for GitHub**. The docs build takes care of +the rest. + +What happens at build time: + +| In README.md (GitHub syntax) | In the docs | +|--------------------------------------------------|---------------------------------------------------------------------------------------------------------| +| Alerts: `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` | Converted into the matching MyST admonition by the local extension `docs/_ext/github_readme.py` | +| Bare URLs (`https://...`, `www....`) | Turned into links by the MyST `linkify` extension | +| `~~strikethrough~~`, task lists `- [ ]` | Rendered by the MyST `strikethrough` and `tasklist` extensions | +| ```` ```mermaid ```` code blocks | Rendered as diagrams through `myst_fence_as_directive` | + +For example, write a note in the README like this: + +```markdown +> [!NOTE] +> We recommend using an absolute path in this file to avoid errors. +``` + +```{warning} +Do not use MyST-only syntax in the README: directives (```` ```{note} ````, `:::`), roles (`` {ref}`...` ``), +targets (`(label)=`), `%` comments or `+++` block breaks. GitHub would show them as raw text. +``` + +Two safeguards catch MyST syntax that slipped into the README: + +- **During the docs build**, the extension prints a warning pointing to the offending line, e.g. + `` README.md:6: WARNING: MyST role in 'See {ref}`x`' will not render on GitHub... `` +- **In CI**, `tests/unit_tests/test_readme.py` fails on the same check. Sphinx warnings do not fail the build, so this + test is what blocks a pull request. It runs with the rest of the unit tests and needs neither Sphinx nor the test + dataset. + +MyST syntax inside a code block is ignored, so you can still show examples of it. + +If you need a GitHub feature that is not in the table above, add the conversion in `docs/_ext/github_readme.py` (the +`include-read` handler only touches files named `README.md`) and a test case in `tests/unit_tests/test_readme.py`. + (heading-adding)= ## Adding to Existing Documentation ➕ @@ -221,6 +264,9 @@ Add this to your `index.md`: ``` ``` +Keep the README written in GitHub-flavored Markdown and load the `github_readme` extension, see +[The README](#readme-doc). + ### Documentation Structure Here's how we organize PANORAMA docs: