Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
108 changes: 108 additions & 0 deletions docs/_ext/github_readme.py
Original file line number Diff line number Diff line change
@@ -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"^> \[!(?P<kind>NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*\n(?P<body>(?:^>.*(?:\n|$))*)",
flags=re.MULTILINE,
)

FENCE = re.compile(r"^ {0,3}(?P<marker>`{3,}|~{3,}|:{3,})(?P<info>.*)$")
# 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<role>\{[\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}
8 changes: 7 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
# -- Imports -----------------------------------------------------------------

import datetime
import sys
from pathlib import Path

import myst_parser
Expand All @@ -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 -----------------------------------------------------

Expand Down Expand Up @@ -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"}
Expand Down
46 changes: 46 additions & 0 deletions docs/developer/buildDoc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 ➕
Expand Down Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
61 changes: 61 additions & 0 deletions tests/unit_tests/test_readme.py
Original file line number Diff line number Diff line change
@@ -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) == []
Loading