climate_ref.baseline_report.render

Write the static HTML report.

Hands frozen objects to Jinja, registers the formatting filters the templates are allowed, and writes the pages out.

CommentLink

One earlier report for the same pull request.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

@frozen
class CommentLink:
    """One earlier report for the same pull request."""

    label: str
    """Short name for the report, typically the head sha it was built from."""

    url: str
    """Where that report is hosted."""

label instance-attribute

Short name for the report, typically the head sha it was built from.

url instance-attribute

Where that report is hosted.

CommentRow

One test case's row in the pull request comment table.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

@frozen
class CommentRow:
    """One test case's row in the pull request comment table."""

    label: str
    """The test case's label, for example ``example/diag/case``."""

    versions: str
    """``v3 -> v4``, or ``new`` / ``removed`` when the case only exists on one side."""

    counts: tuple[str, ...]
    """The ``+a ~c -r`` shorthand per file kind, in the report's column order."""

    url: str
    """Link to the case's page in the hosted report."""

counts instance-attribute

The +a ~c -r shorthand per file kind, in the report's column order.

label instance-attribute

The test case's label, for example example/diag/case.

url instance-attribute

Link to the case's page in the hosted report.

versions instance-attribute

v3 -> v4, or new / removed when the case only exists on one side.

render_case(report, case)

Render one test case's page.

Parameters:

Name	Type	Description	Default
report	AnalysedReport	The analysed report, which carries the header details.	required
case	AnalysedCase	The case to render.	required

Returns:

Type	Description
str	The page's HTML.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

def render_case(report: AnalysedReport, case: AnalysedCase) -> str:
    """
    Render one test case's page.

    Parameters
    ----------
    report
        The analysed report, which carries the header details.
    case
        The case to render.

    Returns
    -------
    :
        The page's HTML.
    """
    return _env.get_template("case.html.j2").render(report=report, case=case)

render_comment(report, base_url, previous=())

Render the pull request comment as markdown.

The comment is one row per changed case and a link into the hosted report, so it stays well inside GitHub's comment size limit however many files moved.

Parameters:

Name	Type	Description	Default
report	AnalysedReport	The analysed report.	required
base_url	str	Where the report is hosted, for example https://reports.example/912/0c7e1d4abc12. A trailing slash is ignored.	required
previous	Sequence[tuple[str, str]]	(label, url) pairs for earlier reports on the same pull request.	()

Returns:

Type	Description
str	The comment's markdown, ending in the marker the CI job finds it by.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

def render_comment(
    report: AnalysedReport,
    base_url: str,
    previous: Sequence[tuple[str, str]] = (),
) -> str:
    """
    Render the pull request comment as markdown.

    The comment is one row per changed case and a link into the hosted report,
    so it stays well inside GitHub's comment size limit however many files moved.

    Parameters
    ----------
    report
        The analysed report.
    base_url
        Where the report is hosted, for example ``https://reports.example/912/0c7e1d4abc12``.
        A trailing slash is ignored.
    previous
        ``(label, url)`` pairs for earlier reports on the same pull request.

    Returns
    -------
    :
        The comment's markdown, ending in the marker the CI job finds it by.
    """
    root = base_url.rstrip("/")
    return _env.get_template("comment.md.j2").render(
        report=report,
        cases=[_comment_row(case, root) for case in report.cases],
        index_url=f"{root}/index.html",
        previous=[CommentLink(label=label, url=url) for label, url in previous],
    )

render_index(report)

Render the overview page.

Parameters:

Name	Type	Description	Default
report	AnalysedReport	The analysed report.	required

Returns:

Type	Description
str	The page's HTML.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

def render_index(report: AnalysedReport) -> str:
    """
    Render the overview page.

    Parameters
    ----------
    report
        The analysed report.

    Returns
    -------
    :
        The page's HTML.
    """
    return _env.get_template("index.html.j2").render(report=report)

write_site(report, out_dir)

Write the overview index.html plus one index.html per case, under the case label.

Parameters:

Name	Type	Description	Default
report	AnalysedReport	The analysed report.	required
out_dir	Path	Directory to write the site into. Created if it does not exist.	required

Returns:

Type	Description
Path	Path of the index page.

Source code in packages/climate-ref/src/climate_ref/baseline_report/render.py

def write_site(report: AnalysedReport, out_dir: Path) -> Path:
    """
    Write the overview ``index.html`` plus one ``index.html`` per case, under the case label.

    Parameters
    ----------
    report
        The analysed report.
    out_dir
        Directory to write the site into. Created if it does not exist.

    Returns
    -------
    :
        Path of the index page.
    """
    out_dir.mkdir(parents=True, exist_ok=True)
    index = out_dir / "index.html"
    index.write_text(render_index(report), encoding="utf-8")
    for case in report.cases:
        page = out_dir / case.change.label / "index.html"
        page.parent.mkdir(parents=True, exist_ok=True)
        page.write_text(render_case(report, case), encoding="utf-8")
    return index