build.py

#!/usr/bin/env python3
"""Builds frogpak.org, the FrogPak/frogpak.github.io Pages site, from a checkout of FrogPak/engine.

Usage: build.py ENGINE_DIR OUTPUT_DIR [ENGINE_SHA]

The home page comes from the engine's README.md and /docs from its docs/.
Links between those files become site links; links to other engine files
go to GitHub. A link to a missing page or heading fails the build.
"""
import html
import re
import shutil
import subprocess
import sys
from pathlib import Path, PurePosixPath
from urllib.parse import urlsplit

from markdown_it import MarkdownIt
from mdit_py_plugins.anchors import anchors_plugin

REPO = "https://github.com/FrogPak/engine"
ORG = "https://github.com/FrogPak"
TEMPLATE = "https://github.com/FrogPak/pond-template"
# README sections about the engine's own source tree, which belong on GitHub only.
DROPPED_SECTIONS = {"This repository"}

STYLE = """
:root {
  --bg: #fafafa; --fg: #1d1d1f; --muted: #5e5c64; --card: #ffffff; --border: #deddda;
  --code: #f0f0f2; --accent: #1c71d8; --on-accent: #ffffff;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #222226; --fg: #f6f5f4; --muted: #c0bfbc; --card: #2e2e32; --border: #3d3846;
    --code: #1a1a1d; --accent: #78aeed; --on-accent: #1d1d1f;
  }
}
* { box-sizing: border-box; }
body {
  margin: 0; background: var(--bg); color: var(--fg);
  font: 16px/1.6 system-ui, -apple-system, "Cantarell", "Segoe UI", sans-serif;
}
header { border-bottom: 1px solid var(--border); background: var(--card); }
.bar {
  max-width: 48rem; margin: 0 auto; padding: .6rem 1rem;
  display: flex; align-items: center; justify-content: space-between; gap: 1rem; flex-wrap: wrap;
}
.brand { display: flex; align-items: center; gap: .6rem; color: var(--fg); text-decoration: none; font-weight: 700; font-size: 1.15rem; }
.brand img { width: 36px; height: 36px; }
nav a { margin-left: 1.1rem; color: var(--fg); text-decoration: none; }
nav a:first-child { margin-left: 0; }
nav a:hover, nav a[aria-current="page"] { color: var(--accent); }
main { max-width: 48rem; margin: 0 auto; padding: 1.5rem 1rem 4rem; }
h1 { font-size: 1.9rem; line-height: 1.2; margin: 1rem 0 1rem; }
h2 { font-size: 1.35rem; margin: 2.25rem 0 .75rem; }
h3 { font-size: 1.1rem; margin: 1.75rem 0 .5rem; }
h1 a.header-anchor { display: none; }
h2 a.header-anchor, h3 a.header-anchor { visibility: hidden; margin-left: .35rem; text-decoration: none; color: var(--muted); }
h2:hover a.header-anchor, h3:hover a.header-anchor { visibility: visible; }
a { color: var(--accent); }
img { max-width: 100%; height: auto; border-radius: 8px; }
code { font: .88em ui-monospace, "Source Code Pro", monospace; background: var(--code); padding: .1em .35em; border-radius: 4px; }
pre { background: var(--code); padding: .8rem 1rem; border-radius: 8px; overflow-x: auto; line-height: 1.45; }
pre code { padding: 0; background: none; font-size: .85rem; }
table { border-collapse: collapse; width: 100%; margin: 0 0 1rem; display: block; overflow-x: auto; }
th, td { border: 1px solid var(--border); padding: .4rem .6rem; text-align: left; vertical-align: top; }
th { background: var(--code); }
td code { white-space: nowrap; }
blockquote { margin: 0 0 1rem; padding: .25rem 1rem; border-left: 4px solid var(--border); color: var(--muted); }
.hero { display: flex; align-items: center; gap: 1.25rem; margin: 1.5rem 0 1rem; }
.hero img { width: 112px; height: 112px; flex: none; border-radius: 0; }
.hero h1 { margin: 0; font-size: 2.4rem; }
.hero p { margin: .25rem 0 0; color: var(--muted); }
.actions { display: flex; gap: .75rem; flex-wrap: wrap; margin: 1.25rem 0 1.5rem; }
.button {
  display: inline-block; padding: .5rem 1.1rem; border-radius: 8px; text-decoration: none;
  border: 1px solid var(--border); color: var(--fg); background: var(--card);
}
.button.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
footer { max-width: 48rem; margin: 0 auto; padding: 0 1rem 2.5rem; font-size: .85rem; color: var(--muted); }
"""

PAGE = """<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{title}</title>
<meta name="description" content="{description}">
<link rel="icon" type="image/svg+xml" href="/favicon.svg">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32.png">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">
<link rel="stylesheet" href="/style.css">
</head>
<body>
<header><div class="bar">
<a class="brand" href="/"><img src="/logo.svg" alt="">FrogPak</a>
<nav>{nav}</nav>
</div></header>
<main>
{body}
</main>
<footer>{footer}</footer>
</body>
</html>
"""

NAV = (("Docs", "/docs/"), ("Demo", "/demo/"), ("GitHub", ORG))
DESCRIPTION = "FrogPak turns a GitHub repository into a signed Flatpak remote hosted on GitHub Pages."


class BuildError(Exception):
    pass


def site_path(source):
    """Site URL path for an engine Markdown file, or None when it is not published."""
    source = PurePosixPath(source)
    if source == PurePosixPath("README.md"):
        return "/"
    if source.parent == PurePosixPath("docs") and source.suffix == ".md":
        return "/docs/" if source.name == "README.md" else f"/docs/{source.stem}.html"
    return None


def out_file(url_path):
    return url_path.lstrip("/") + "index.html" if url_path.endswith("/") else url_path.lstrip("/")


def split_sections(text):
    """Removes level-2 sections listed in DROPPED_SECTIONS."""
    out, skipping, fence = [], False, False
    for line in text.split("\n"):
        if line.lstrip().startswith("```"):
            fence = not fence
        if not fence and line.startswith("## "):
            skipping = line[3:].strip() in DROPPED_SECTIONS
        if not skipping:
            out.append(line)
    return "\n".join(out)


class Site:
    def __init__(self, engine, out, sha):
        self.engine = Path(engine)
        self.out = Path(out)
        self.sha = sha
        self.pages = {}      # url path -> (source, html body, title)
        self.anchors = {}    # url path -> set of ids
        self.links = []      # (from source, url path, fragment)
        self.assets = set()  # engine-relative paths to copy

    def rewrite(self, source, href):
        parts = urlsplit(href)
        if parts.scheme or parts.netloc or href.startswith(("mailto:", "/")):
            return href
        if not parts.path:
            self.links.append((source, site_path(source), parts.fragment))
            return href
        target = (PurePosixPath(source).parent / parts.path)
        resolved = PurePosixPath(*[p for p in _normalize(target.parts)])
        if not (self.engine / resolved).exists():
            raise BuildError(f"{source}: link to missing file {href}")
        url = site_path(resolved)
        if url is not None:
            self.links.append((source, url, parts.fragment))
            return url + (f"#{parts.fragment}" if parts.fragment else "")
        if resolved.parts[:2] == ("docs", "images"):
            self.assets.add(resolved)
            return "/" + str(resolved)
        kind = "tree" if (self.engine / resolved).is_dir() else "blob"
        return f"{REPO}/{kind}/main/{resolved}" + (f"#{parts.fragment}" if parts.fragment else "")

    def render(self, source):
        text = (self.engine / source).read_text()
        if source == "README.md":
            text = split_sections(text)
        # CommonMark, as on GitHub, so code blocks inside list items render; heading ids follow GitHub's.
        md = (MarkdownIt("commonmark").enable(["table", "strikethrough"])
              .use(anchors_plugin, min_level=1, max_level=4, permalink=True, permalinkSymbol="#"))
        body = md.render(text)
        body = re.sub(r'(href|src)="([^"]*)"',
                      lambda m: f'{m.group(1)}="{html.escape(self.rewrite(source, html.unescape(m.group(2))))}"',
                      body)
        ids = set(re.findall(r'\sid="([^"]+)"', body))
        title_match = re.search(r"<h1[^>]*>(.*?)</h1>", body, re.S)
        title = re.sub(r"<[^>]+>", "", title_match.group(1)).strip() if title_match else "FrogPak"
        return body, ids, title

    def build(self):
        sources = ["README.md"] + sorted(str(p.relative_to(self.engine))
                                         for p in (self.engine / "docs").glob("*.md"))
        for source in sources:
            body, ids, title = self.render(source)
            url = site_path(source)
            self.pages[url] = (source, body, title)
            self.anchors[url] = ids
        for source, url, fragment in self.links:
            if url not in self.pages:
                raise BuildError(f"{source}: link to unpublished page {url}")
            if fragment and fragment not in self.anchors[url]:
                raise BuildError(f"{source}: link to missing heading {url}#{fragment}")

        if self.out.exists():
            shutil.rmtree(self.out)
        self.out.mkdir(parents=True)
        for url, (source, body, title) in self.pages.items():
            if url == "/":
                body = home(body)
                page_title = "FrogPak: Flatpak remotes on GitHub Pages"
            else:
                page_title = f"{title} | FrogPak"
            dest = self.out / out_file(url)
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_text(PAGE.format(title=html.escape(page_title), description=html.escape(DESCRIPTION),
                                        nav=nav(url), body=body, footer=self.footer(source)))
        for asset in self.assets:
            dest = self.out / asset
            dest.parent.mkdir(parents=True, exist_ok=True)
            shutil.copyfile(self.engine / asset, dest)
        (self.out / "style.css").write_text(STYLE.lstrip())
        self.icons()
        (self.out / "404.html").write_text(PAGE.format(
            title="Not found | FrogPak", description=html.escape(DESCRIPTION), nav=nav(""),
            body='<h1>Not found</h1>\n<p>There is no page at this address. Try the <a href="/docs/">documentation</a>.</p>',
            footer=""))
        # Pages would otherwise run Jekyll over the output.
        (self.out / ".nojekyll").write_text("")

    def icons(self):
        logo = self.engine / "frogpak" / "data" / "default-logo.svg"
        shutil.copyfile(logo, self.out / "logo.svg")
        shutil.copyfile(logo, self.out / "favicon.svg")
        for name, size in (("favicon-32.png", 32), ("apple-touch-icon.png", 180)):
            subprocess.run(["rsvg-convert", "-w", str(size), "-h", str(size), "-o", str(self.out / name), str(logo)],
                           check=True)

    def footer(self, source):
        version = f' at <a href="{REPO}/commit/{self.sha}">{self.sha[:7]}</a>' if self.sha else ""
        return (f'From <a href="{REPO}/blob/main/{source}">{html.escape(source)}</a> in FrogPak/engine{version}. '
                f'Corrections are welcome as issues or pull requests there.')


def _normalize(parts):
    out = []
    for part in parts:
        if part in ("", "."):
            continue
        if part == "..":
            if not out:
                raise BuildError("link leaves the engine repository")
            out.pop()
        else:
            out.append(part)
    return out


def nav(current):
    links = []
    for label, href in NAV:
        here = ' aria-current="page"' if current.startswith(href) and href.startswith("/") and current else ""
        links.append(f'<a href="{href}"{here}>{label}</a>')
    return "".join(links)


def home(body):
    """Replaces the README's title with the logo, tagline and the main actions."""
    body = re.sub(r"<h1[^>]*>.*?</h1>\s*", "", body, count=1, flags=re.S)
    tagline = re.search(r"<p>(.*?)</p>", body, re.S)
    if tagline:
        body = body[:tagline.start()] + body[tagline.end():]
    hero = ('<div class="hero"><img src="/logo.svg" alt="FrogPak: a golden mantella frog peeking out of a blue box">'
            f'<div><h1>FrogPak</h1>{"<p>" + tagline.group(1) + "</p>" if tagline else ""}</div></div>\n'
            '<div class="actions">'
            f'<a class="button primary" href="{TEMPLATE}">Start a Pond</a>'
            '<a class="button" href="/docs/setup.html">Setup guide</a>'
            '<a class="button" href="/demo/">See a demo Pond</a>'
            '</div>\n')
    return hero + body


def main():
    if len(sys.argv) not in (3, 4):
        print(__doc__.split("\n\n")[1], file=sys.stderr)
        return 2
    try:
        Site(sys.argv[1], sys.argv[2], sys.argv[3] if len(sys.argv) == 4 else "").build()
    except BuildError as error:
        print(f"::error::{error}")
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())