#!/usr/bin/env python3
"""Builds the HTML documents from their Markdown sources.

    python docs/build_docs.py          # rebuild the HTML
    python docs/build_docs.py --check  # exit 1 if any HTML is out of date (for CI)
    python docs/build_docs.py --publish  # rebuild, then upload docs/ to the web server (tools/publish_docs.py)

The HTML files (USER_GUIDE.html, HARDWARE_OVERVIEW.html, FAQ.html) are the default way to read the
documents. They are self-contained: stylesheet, diagrams (inlined from docs/diagrams/*.svg) and
pictures (embedded as downscaled JPEGs) are all inside the file, so one file can be e-mailed or
copied to a USB stick. The Markdown stays the editable source (GitHub renders it too), so edit
that and re-run this script; do not edit the HTML by hand.

The script also writes src/docs_data.h: a gzipped copy of each page, embedded in the firmware so
the unit serves its own documents at /docs/USER_GUIDE.html, /docs/HARDWARE_OVERVIEW.html and /docs/FAQ.html (see
device_copy() for how the on-device copy differs: always dark, no links to files that are not on
the unit, a link back to the settings page).

No third-party packages: this is a small converter for the Markdown subset the documents use
(headings, paragraphs, nested lists, tables, block quotes, images, rules, **bold**, *italic*,
`code` and links). Pillow is used only if present, to embed photographs.
"""
import base64
import gzip
import hashlib
import io
import os
import re
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
SITE = "Uncle Magic's Liquid Turntable"
DOCS = [("USER_GUIDE", "User Guide"), ("HARDWARE_OVERVIEW", "Hardware Overview"), ("FAQ", "FAQ")]
DOC_NAMES = {name + ".md" for name, _ in DOCS}

# ----------------------------------------------------------------------------------------------
# inline text

def esc(s):
    s = re.sub(r"&(?!#?\w+;)", "&amp;", s)
    return s.replace("<", "&lt;").replace(">", "&gt;")


def slug(text):
    s = re.sub(r"[`*]", "", text).lower()
    s = re.sub(r"[^\w\s\-]", "", s)
    return re.sub(r"\s", "-", s.strip())


def fix_href(href):
    """Links between the documents point at the HTML versions."""
    path, hash_, frag = href.partition("#")
    if path in DOC_NAMES:
        path = path[:-3] + ".html"
    return path + (hash_ + frag if hash_ else "")


def inline(s):
    codes = []

    def stash(m):
        codes.append(m.group(1))
        return "\x00%d\x00" % (len(codes) - 1)

    s = re.sub(r"`([^`]+)`", stash, s)
    s = esc(s)

    def link(m):
        text, href = m.group(1), m.group(2)
        href = fix_href(href)
        extra = ' target="_blank" rel="noopener"' if re.match(r"https?:", href) else ""
        return '<a href="%s"%s>%s</a>' % (href, extra, text)

    s = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", link, s)
    s = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", s)
    s = re.sub(r"(?<![\*\w])\*(?!\s)(.+?)(?<!\s)\*(?![\*\w])", r"<em>\1</em>", s)
    return re.sub(r"\x00(\d+)\x00", lambda m: "<code>%s</code>" % esc(codes[int(m.group(1))]), s)


# ----------------------------------------------------------------------------------------------
# images

def figure(alt, src):
    path = os.path.normpath(os.path.join(HERE, src))
    if not os.path.exists(path):
        sys.exit("missing image: %s" % src)
    if path.lower().endswith(".svg"):
        svg = open(path, encoding="utf-8").read()
        svg = re.sub(r"<\?xml.*?\?>", "", svg).strip()
        body = svg
    elif "screenshots" in src.replace("\\", "/").split("/"):
        # UI screenshots stay PNG (sharp text) at their own size, centred rather than stretched
        try:
            from PIL import Image
        except ImportError:
            sys.exit("Pillow is needed to embed %s (pip install pillow)" % src)
        im = Image.open(path).convert("RGB")
        buf = io.BytesIO()
        im.save(buf, "PNG", optimize=True)
        data = base64.b64encode(buf.getvalue()).decode("ascii")
        body = '<img alt="%s" src="data:image/png;base64,%s" width="%d" height="%d">' % (esc(alt), data, im.width, im.height)
        return '<figure class="shot">%s<figcaption>%s</figcaption></figure>' % (body, inline(alt))
    else:
        try:
            from PIL import Image
        except ImportError:
            sys.exit("Pillow is needed to embed %s (pip install pillow)" % src)
        im = Image.open(path).convert("RGB")
        if im.width > 1100:
            im = im.resize((1100, round(im.height * 1100 / im.width)), getattr(Image, "Resampling", Image).LANCZOS)
        buf = io.BytesIO()
        im.save(buf, "JPEG", quality=82, optimize=True)
        data = base64.b64encode(buf.getvalue()).decode("ascii")
        body = '<img alt="%s" src="data:image/jpeg;base64,%s">' % (esc(alt), data)
    return "<figure>%s<figcaption>%s</figcaption></figure>" % (body, inline(alt))


# ----------------------------------------------------------------------------------------------
# blocks

LIST_RE = re.compile(r"^(\s*)([-*+]|\d+[.)])\s+(.*)$")
HEAD_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
HR_RE = re.compile(r"^\s*(-{3,}|\*{3,}|_{3,})\s*$")
TABLE_SEP_RE = re.compile(r"^\s*\|?[\s:\-|]+\|?\s*$")
IMG_RE = re.compile(r"^\s*!\[([^\]]*)\]\(([^)\s]+)\)\s*$")


def indent(line):
    return len(line) - len(line.lstrip(" "))


def starts_block(lines, i):
    line = lines[i]
    return bool(
        HEAD_RE.match(line) or HR_RE.match(line) or LIST_RE.match(line)
        or line.lstrip().startswith(">") or line.lstrip().startswith("```")
        or IMG_RE.match(line)
        or (line.lstrip().startswith("|") and i + 1 < len(lines) and TABLE_SEP_RE.match(lines[i + 1]))
    )


def split_row(line):
    line = line.strip()
    if line.startswith("|"):
        line = line[1:]
    if line.endswith("|") and not line.endswith("\\|"):
        line = line[:-1]
    return [c.strip().replace("\\|", "|") for c in re.split(r"(?<!\\)\|", line)]


def render_table(rows, aligns):
    head, body = rows[0], rows[1:]

    def cell(tag, text, a):
        style = ' style="text-align:%s"' % a if a else ""
        return "<%s%s>%s</%s>" % (tag, style, inline(text), tag)

    out = ['<div class="table-wrap"><table><thead><tr>']
    out += [cell("th", c, aligns[k] if k < len(aligns) else "") for k, c in enumerate(head)]
    out.append("</tr></thead><tbody>")
    for r in body:
        out.append("<tr>")
        out += [cell("td", c, aligns[k] if k < len(aligns) else "") for k, c in enumerate(r)]
        out.append("</tr>")
    out.append("</tbody></table></div>")
    return "".join(out)


def parse_list(lines, i):
    m = LIST_RE.match(lines[i])
    base = len(m.group(1))
    ordered = m.group(2)[0].isdigit()
    n = len(lines)
    items = []
    while i < n:
        m = LIST_RE.match(lines[i])
        if not (m and len(m.group(1)) == base and m.group(2)[0].isdigit() == ordered):
            break
        first = m.group(3)
        i += 1
        cont = []
        while i < n:
            line = lines[i]
            if not line.strip():
                j = i
                while j < n and not lines[j].strip():
                    j += 1
                if j < n and indent(lines[j]) > base:
                    cont.append("")
                    i += 1
                    continue
                break
            if indent(line) > base:
                cont.append(line)
                i += 1
            else:
                break
        nonblank = [indent(c) for c in cont if c.strip()]
        d = min(nonblank) if nonblank else 0
        item_lines = [first] + [c[d:] if c.strip() else "" for c in cont]
        items.append(item_lines)
        # a blank line between two items of the same list does not end the list
        j = i
        while j < n and not lines[j].strip():
            j += 1
        if j > i and j < n:
            m2 = LIST_RE.match(lines[j])
            if m2 and len(m2.group(1)) == base and m2.group(2)[0].isdigit() == ordered:
                i = j
    tag = "ol" if ordered else "ul"
    out = ["<%s>" % tag]
    for item_lines in items:
        blocks = parse_blocks(item_lines)
        parts = []
        for k, (kind, data) in enumerate(blocks):
            if kind == "p" and k == 0 and all(b[0] != "p" for b in blocks[1:]):
                parts.append(data)  # tight item: no <p> around the first paragraph
            else:
                parts.append(block_html(kind, data))
        out.append("<li>%s</li>" % "".join(parts))
    out.append("</%s>" % tag)
    return "".join(out), i


def block_html(kind, data):
    if kind == "p":
        return "<p>%s</p>" % data
    return data


def parse_blocks(lines):
    """Returns [(kind, html)] with kind in p, html, h (data = (level, raw)), hr."""
    out = []
    i, n = 0, len(lines)
    while i < n:
        line = lines[i]
        if not line.strip():
            i += 1
            continue
        if line.lstrip().startswith("```"):
            lang = line.strip()[3:].strip()
            i += 1
            buf = []
            while i < n and not lines[i].lstrip().startswith("```"):
                buf.append(lines[i])
                i += 1
            i += 1
            out.append(("html", '<pre><code class="lang-%s">%s</code></pre>' % (lang, esc("\n".join(buf)))))
            continue
        m = HEAD_RE.match(line)
        if m:
            out.append(("h", (len(m.group(1)), m.group(2))))
            i += 1
            continue
        if HR_RE.match(line):
            out.append(("hr", "<hr>"))
            i += 1
            continue
        m = IMG_RE.match(line)
        if m:
            out.append(("html", figure(m.group(1), m.group(2))))
            i += 1
            continue
        if line.lstrip().startswith("|") and i + 1 < n and TABLE_SEP_RE.match(lines[i + 1]):
            header = split_row(line)
            sep = split_row(lines[i + 1])
            aligns = []
            for c in sep:
                c = c.strip()
                aligns.append("center" if c.startswith(":") and c.endswith(":") else "right" if c.endswith(":") else "")
            rows = [header]
            i += 2
            while i < n and lines[i].lstrip().startswith("|"):
                rows.append(split_row(lines[i]))
                i += 1
            out.append(("html", render_table(rows, aligns)))
            continue
        if line.lstrip().startswith(">"):
            buf = []
            while i < n and lines[i].lstrip().startswith(">"):
                buf.append(re.sub(r"^\s*>\s?", "", lines[i]))
                i += 1
            inner = "".join(block_html(k, d) for k, d in parse_blocks(buf))
            out.append(("html", '<blockquote class="callout">%s</blockquote>' % inner))
            continue
        if LIST_RE.match(line):
            html_, i = parse_list(lines, i)
            out.append(("html", html_))
            continue
        buf = []
        while i < n and lines[i].strip() and not (buf and starts_block(lines, i)):
            buf.append(lines[i].strip())
            i += 1
        out.append(("p", inline(" ".join(buf))))
    return out


# ----------------------------------------------------------------------------------------------
# page

CSS = r"""
:root{--bg:#fff;--fg:#1f2328;--muted:#59636e;--line:#d1d9e0;--soft:#f6f8fa;--accent:#0b6e8a;
--warn:#9a6700;--warn-bg:#fff8e1;--code:#eff1f3}
@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#9198a1;--line:#30363d;
--soft:#161b22;--accent:#4cc3e0;--warn:#e3b341;--warn-bg:#2a2208;--code:#262c36}}
*{box-sizing:border-box}
html{scroll-behavior:smooth;scroll-padding-top:4.5rem;-webkit-text-size-adjust:100%}
body{margin:0;background:var(--bg);color:var(--fg);
font:16px/1.65 system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",sans-serif}
.topbar{position:sticky;top:0;z-index:5;background:var(--bg);border-bottom:1px solid var(--line)}
.topbar .in{max-width:70rem;margin:0 auto;padding:.65rem 1.25rem;display:flex;gap:.4rem 1.5rem;
align-items:baseline;flex-wrap:wrap}
.brand{font-weight:700;letter-spacing:.01em}
.topbar nav{display:flex;gap:1.1rem;flex-wrap:wrap}
.topbar nav a{color:var(--muted);text-decoration:none;font-size:.95rem;padding-bottom:.1rem;
border-bottom:2px solid transparent}
.topbar nav a:hover{color:var(--accent)}
.topbar nav a.back{margin-right:.6rem;padding-right:1.1rem;border-right:1px solid var(--line)}
.topbar nav a[aria-current=page]{color:var(--accent);border-bottom-color:var(--accent);font-weight:600}
.layout{max-width:70rem;margin:0 auto;padding:1.5rem 1.25rem 4rem;display:grid;
grid-template-columns:14.5rem minmax(0,1fr);gap:2.5rem}
.toc{position:sticky;top:4.6rem;align-self:start;max-height:calc(100vh - 6rem);overflow:auto;font-size:.9rem}
.toc summary{cursor:pointer;font-weight:600;padding:.3rem 0;color:var(--muted)}
.toc a{display:block;padding:.28rem .7rem;border-left:2px solid var(--line);color:var(--muted);
text-decoration:none;line-height:1.35}
.toc a:hover{color:var(--accent);border-left-color:var(--accent)}
main{min-width:0;max-width:50rem}
h1{font-size:2rem;line-height:1.2;margin:.2rem 0 1rem}
h2{font-size:1.45rem;line-height:1.3;margin:2.6rem 0 .8rem;padding-bottom:.35rem;border-bottom:1px solid var(--line)}
h3{font-size:1.15rem;margin:1.9rem 0 .5rem}
.anchor{margin-left:.45rem;opacity:0;text-decoration:none;color:var(--muted);font-weight:400}
h2:hover .anchor,h3:hover .anchor,.anchor:focus{opacity:1}
p,li{overflow-wrap:break-word}
li{margin:.25rem 0}
li>ul,li>ol{margin:.3rem 0}
a{color:var(--accent)}
strong{font-weight:650}
code{font:.88em ui-monospace,SFMono-Regular,Consolas,"Liberation Mono",monospace;background:var(--code);
padding:.12em .35em;border-radius:.3em;overflow-wrap:anywhere}
pre{background:var(--code);padding:.9rem 1rem;border-radius:.5rem;overflow:auto}
pre code{background:none;padding:0}
.table-wrap{overflow-x:auto;margin:1.1rem 0;border:1px solid var(--line);border-radius:.55rem}
table{border-collapse:collapse;width:100%;font-size:.93rem}
th,td{padding:.55rem .8rem;text-align:left;vertical-align:top;border-bottom:1px solid var(--line)}
thead th{background:var(--soft);font-weight:600}
tbody tr:last-child td{border-bottom:0}
tbody tr:nth-child(even){background:color-mix(in srgb,var(--soft) 60%,transparent)}
blockquote.callout{margin:1.2rem 0;padding:.7rem 1rem;border-left:4px solid var(--warn);
background:var(--warn-bg);border-radius:.35rem}
blockquote.callout p{margin:.4rem 0}
figure{margin:1.5rem 0}
figure svg,figure img{width:100%;height:auto;display:block;border-radius:.4rem}
figure.shot img{width:auto;max-width:100%;margin:0 auto}
figcaption{color:var(--muted);font-size:.85rem;margin-top:.45rem;text-align:center}
hr{border:0;border-top:1px solid var(--line);margin:2.2rem 0}
footer{margin-top:3.5rem;padding-top:1rem;border-top:1px solid var(--line);color:var(--muted);font-size:.85rem}
@media (min-width:64rem){.toc summary{display:none}}
@media (max-width:63.99rem){
.layout{grid-template-columns:minmax(0,1fr);gap:1rem}
.toc{position:static;max-height:none;border:1px solid var(--line);border-radius:.55rem;padding:.2rem .8rem}
h1{font-size:1.65rem}}
@media print{
:root{--bg:#fff;--fg:#000;--muted:#333;--line:#bbb;--soft:#f3f3f3;--accent:#000;--code:#eee;--warn-bg:#f6f6f6}
.topbar,.toc,.anchor{display:none}.layout{display:block;padding:0}main{max-width:none}
a{text-decoration:none}h2,h3{break-after:avoid}figure,table,tr{break-inside:avoid}}
"""

PAGE = """<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="light dark">
<title>{title}</title>
<style>{css}</style>
</head>
<body>
<header class="topbar"><div class="in">
<span class="brand">{site}</span>
<nav aria-label="Documents">{nav}</nav>
</div></header>
<div class="layout">
<aside class="toc"><details open><summary>On this page</summary>
{toc}
</details></aside>
<main>
{body}
<footer>Built from <code>{src}</code> by <code>docs/build_docs.py</code>. To change this page, edit the
Markdown and run the script again.</footer>
</main>
</div>
<script>
if (window.matchMedia('(max-width: 63.99rem)').matches) {{
  var d = document.querySelector('.toc details'); if (d) d.open = false;
}}
</script>
</body>
</html>
"""


def build(name, label, check=False):
    src = os.path.join(HERE, name + ".md")
    lines = open(src, encoding="utf-8").read().split("\n")
    blocks = parse_blocks(lines)

    # The Markdown opens with a "Contents" list; the page has a sidebar instead.
    cleaned = []
    skip = False
    for kind, data in blocks:
        if kind == "h" and data[0] == 2 and data[1].strip().lower() == "contents":
            skip = True
            continue
        if skip:
            if kind in ("html", "p"):
                continue
            skip = False
            if kind == "hr":
                continue
        cleaned.append((kind, data))

    body, toc, title = [], [], name
    for kind, data in cleaned:
        if kind == "h":
            level, raw = data
            plain = re.sub(r"[`*]", "", raw)
            sid = slug(raw)
            if level == 1:
                title = plain
            body.append('<h%d id="%s">%s<a class="anchor" href="#%s" aria-label="Link to this section">#</a></h%d>'
                        % (level, sid, inline(raw), sid, level))
            if level == 2:
                toc.append('<a href="#%s">%s</a>' % (sid, inline(raw)))
        else:
            body.append(block_html(kind, data))

    nav = '<a class="back" href="index.html">&larr; All documentation</a>' + "".join(
        '<a href="%s.html"%s>%s</a>' % (n, ' aria-current="page"' if n == name else "", lbl) for n, lbl in DOCS
    )
    page = PAGE.format(title=esc(title), css=CSS.strip(), site=esc(SITE), nav=nav,
                       toc="\n".join(toc), body="\n".join(body), src=name + ".md")
    out = os.path.join(HERE, name + ".html")
    if check:
        try:
            current = open(out, encoding="utf-8", newline="").read().replace("\r\n", "\n")
        except FileNotFoundError:
            current = None
        return out, len(page), current == page
    open(out, "w", encoding="utf-8", newline="\n").write(page)
    return out, len(page), True


# ----------------------------------------------------------------------------------------------
# copy embedded in the firmware

HEADER = os.path.join(os.path.dirname(HERE), "src", "docs_data.h")


def nav_macro(name):
    """A string macro from src/web_nav.h (NAV_CSS or NAV_HTML): its quoted pieces joined. The file keeps
    them free of double quotes and backslashes, so no unescaping is needed."""
    text = open(os.path.join(HERE, "..", "src", "web_nav.h"), encoding="utf-8").read()
    m = re.search(r"#define %s \\\n((?:.*\\\n)*.*\n)" % name, text)
    if not m:
        raise SystemExit("web_nav.h: no %s" % name)
    return "".join(re.findall(r'"([^"]*)"', m.group(1)))


# Where docs/ is published (.github/workflows/publish-docs.yml): the unit's copies link files it doesn't serve there.
DOCS_SITE = "https://kennedy-williams.net/unclemagic/docs/"


def device_copy(page):
    """The page as the unit serves it: dark to match the unit's own pages, links to repository
    files that are not on the unit turned into plain text, links to the fixture files (docs/fixtures, not on the
    unit) pointed at the published documentation index's list of them (over HTTPS: a download started from the
    unit's plain-HTTP page is blocked), opening in a new window, and the unit's own menu
    (src/web_nav.h) in place of the documents' top bar, so every page the unit serves has the same menu."""
    page = page.replace("@media (prefers-color-scheme:dark){", "@media all{", 1)
    page = page.replace('<meta name="color-scheme" content="light dark">', '<meta name="color-scheme" content="dark">', 1)
    page = page.replace("--accent:#4cc3e0", "--accent:#a99cff", 1)
    page = re.sub(r'<a href="(?:\.\./|files/)[^"]*">(.*?)</a>', r"\1", page, flags=re.S)
    page = re.sub(r'<a href="fixtures/[^"]*"', '<a target="_blank" rel="noopener" href="' + DOCS_SITE + 'index.html#fixtures"', page)
    page = re.sub(r'<a href="index\.html(#[^"]*)?"', lambda m: '<a target="_blank" rel="noopener" href="' + DOCS_SITE +
                  'index.html' + (m.group(1) or '') + '"', page)
    page = re.sub(r'<header class="topbar">.*?</header>', lambda m: nav_macro("NAV_HTML"), page, count=1, flags=re.S)
    page = page.replace("</style>", nav_macro("NAV_CSS") + ".um{margin:0;padding:.6rem 1.25rem}</style>", 1)
    return page


def header_text():
    """Text of src/docs_data.h. Each document is recorded with the SHA-256 of its on-device HTML so
    --check can tell whether the header is current without depending on gzip's exact output."""
    out = ["// Generated by docs/build_docs.py from docs/*.md. Do not edit; run: python docs/build_docs.py",
           "// Gzipped HTML of the documents, served by the unit at /docs/<name>.html.",
           "#pragma once", "#include <stdint.h>", "#include <stddef.h>", ""]
    for name, _ in DOCS:
        html = device_copy(open(os.path.join(HERE, name + ".html"), encoding="utf-8", newline="").read().replace("\r\n", "\n"))
        raw = html.encode("utf-8")
        blob = gzip.compress(raw, 9, mtime=0)
        out.append("// %s.html  source-sha256: %s  (%d bytes, %d gzipped)" % (name, hashlib.sha256(raw).hexdigest(), len(raw), len(blob)))
        out.append("const uint8_t DOC_%s_GZ[] PROGMEM = {" % name)
        for i in range(0, len(blob), 24):
            out.append("  " + ",".join("0x%02x" % b for b in blob[i:i + 24]) + ",")
        out.append("};")
        out.append("const size_t DOC_%s_GZ_LEN = %d;" % (name, len(blob)))
        out.append("")
    return "\n".join(out)


def header_fresh(text):
    """True if the existing header was generated from the same on-device HTML as `text` would be."""
    try:
        current = open(HEADER, encoding="utf-8", newline="").read().replace("\r\n", "\n")
    except FileNotFoundError:
        return False
    pat = re.compile(r"source-sha256: ([0-9a-f]{64})")
    return pat.findall(current) == pat.findall(text)


if __name__ == "__main__":
    check = "--check" in sys.argv[1:]
    stale = []
    for n, lbl in DOCS:
        path, size, fresh = build(n, lbl, check)
        rel = os.path.relpath(path, os.path.dirname(HERE))
        if check:
            print("%-32s %s" % (rel, "up to date" if fresh else "OUT OF DATE"))
            if not fresh:
                stale.append(rel)
        else:
            print("%-32s %6.0f KB" % (rel, size / 1024))
    text = header_text()
    if check:
        fresh = header_fresh(text)
        rel = os.path.relpath(HEADER, os.path.dirname(HERE))
        print("%-32s %s" % (rel, "up to date" if fresh else "OUT OF DATE"))
        if not fresh:
            stale.append(rel)
    else:
        os.makedirs(os.path.dirname(HEADER), exist_ok=True)
        open(HEADER, "w", encoding="utf-8", newline="\n").write(text)
        print("%-32s %6.0f KB" % (os.path.relpath(HEADER, os.path.dirname(HERE)), len(text) / 1024))
    if stale:
        sys.exit("Rebuild with: python docs/build_docs.py")
    if "--publish" in sys.argv[1:] and not check:
        import subprocess
        sys.exit(subprocess.call([sys.executable, os.path.join(os.path.dirname(HERE), "tools", "publish_docs.py")]))
