xiview-server/build_docs.py at pride · Rappsilber-Laboratory/xiview-server · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
#!/usr/bin/env python3
"""Build HTML docs from markdown sources.

Usage: python build_docs.py

Reads:  docs/md/**/*.md
Writes: static/xidocs/html/**/*.html  (generated — do not edit directly)
Syncs:  docs/img/*  →  static/xidocs/img/
"""

import os
import shutil
from pathlib import Path

import markdown

DOCS_MD = Path("docs/md")
DOCS_IMG = Path("docs/img")
DOCS_VID = Path("docs/vid")
OUT_HTML = Path("static/xidocs/html")
OUT_IMG = Path("static/xidocs/img")
OUT_VID = Path("static/xidocs/vid")

TEMPLATE = """\
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{title}</title>
<link rel="stylesheet" href="{css_path}" />
</head>
<body>
{content}
</body>
</html>
<!-- Generated from docs/md/{rel} — do not edit directly -->
"""


def build_html():
    count = 0
    for md_path in sorted(DOCS_MD.rglob("*.md")):
        rel = md_path.relative_to(DOCS_MD)          # e.g. views/histogram.md
        depth = len(rel.parts)                        # 1 or 2
        css_path = "../" * depth + "docs.css"

        title = md_path.stem
        src = md_path.read_text(encoding="utf-8")
        content = markdown.markdown(src, extensions=["tables", "fenced_code", "admonition", "toc"])

        html = TEMPLATE.format(
            title=title,
            css_path=css_path,
            content=content,
            rel=str(rel),
        )

        out_path = OUT_HTML / rel.with_suffix(".html")
        out_path.parent.mkdir(parents=True, exist_ok=True)
        out_path.write_text(html, encoding="utf-8")
        print(f"  wrote {out_path}")
        count += 1

    return count


def sync_images():
    OUT_IMG.mkdir(parents=True, exist_ok=True)
    copied = 0
    for img in sorted(DOCS_IMG.iterdir()):
        if img.is_file():
            shutil.copy2(img, OUT_IMG / img.name)
            copied += 1
    return copied


def sync_videos():
    OUT_VID.mkdir(parents=True, exist_ok=True)
    copied = 0
    for vid in sorted(DOCS_VID.iterdir()):
        if vid.is_file():
            shutil.copy2(vid, OUT_VID / vid.name)
            copied += 1
    return copied


if __name__ == "__main__":
    print("Building HTML from markdown…")
    n_html = build_html()
    print("Syncing images…")
    n_img = sync_images()
    # print("Syncing videos…")
    # n_vid = sync_videos()
    print(f"Done: {n_html} HTML files written, {n_img} images synced.")