Project Chimera
Меню

Исходники

452 строк · 23 КиБ

packaging/site/build.py

1#!/usr/bin/env python3
2"""Собирает публичные страницы лаунчера на project-chimera.ru.
3
4Почему сборщик, а не пять готовых файлов: шапка, подвал и навигация у всех
5страниц общие, и держать их в пяти копиях — значит однажды поправить четыре
6из пяти. Здесь общий каркас один (`template.html`), а страницы — только своё
7содержимое (`pages/*.html`).
8
9Почему свой, а не генератор статики: зависимостей у него ноль, и ставить
10ради пяти страниц Hugo или Eleventy на машину, где их больше никто не
11попросит, несоразмерно.
12
13Две страницы собираются из документов репозитория, а не пишутся вручную:
14«что сделано» — из `ROADMAP.md`, журнал разработки — из `DEVLOG.md`. Копия
15этих текстов на сайте разошлась бы с репозиторием в первый же день.
16"""
17
18from __future__ import annotations
19
20import hashlib
21import html
22import pathlib
23import re
24import shutil
25import sys
26
27HERE = pathlib.Path(__file__).resolve().parent
28REPO = HERE.parent.parent
29OUT = HERE / "out"
30
31# id страницы → (файл тела, заголовок, описание для поисковиков)
32PAGES = {
33 "index": ("index.html", "Лаунчер Windows-игр для Linux",
34 "Chimera Launcher: библиотека, витрины Steam, Epic и GOG, сборки Wine, "
35 "настройки под каждую игру. Без телеметрии."),
36 "wiki": ("wiki.html", "Справка",
37 "Все разделы Chimera Launcher по порядку: где что искать, как пользоваться "
38 "и что оно делает."),
39 "db": ("db.html", "База запусков",
40 "Какие игры запускаются, на какой сборке Wine и с какими настройками — "
41 "по отчётам из самого лаунчера."),
42 "source": ("source.html", "Исходники и работа",
43 "Из чего собран Chimera Launcher, что уже сделано и журнал разработки."),
44 "review": ("review.html", "Посмотреть и раскритиковать",
45 "Chimera Launcher: зачем он написан, какие решения спорные и что автор "
46 "сам считает слабым местом."),
47 "privacy": ("privacy.html", "Приватность",
48 "Что Chimera Launcher отправляет в сеть, когда и что именно. "
49 "Телеметрии нет."),
50}
51
52# Сколько записей журнала показывать. Весь `DEVLOG.md` — это сотни килобайт
53# текста: страница из него собралась бы неподъёмной, а читать её с начала
54# всё равно никто не станет.
55DEVLOG_ENTRIES = 6
56
57
58def version() -> str:
59 return (REPO / "code" / "version.txt").read_text(encoding="utf-8").strip()
60
61
62def style_v() -> str:
63 """Чем биться кэшу таблицы стилей.
64
65 Здесь стоял номер версии лаунчера, и это было сломано незаметно:
66 правка стилей с выпуском не связана, поэтому изменение внутри одной
67 версии до вернувшегося посетителя не доезжало — адрес файла не
68 менялся, и браузер отдавал прежнее содержимое из кэша. Нашлось
69 замером: страница продолжала применять правило, которое из файла
70 уже удалили, а на хосте лежал новый файл.
71
72 Теперь адрес меняется тогда и только тогда, когда меняется само
73 содержимое.
74 """
75 return hashlib.sha256((HERE / "style.css").read_bytes()).hexdigest()[:12]
76
77
78def markdown_to_html(text: str) -> str:
79 """Разбор нарочно узкий — ровно то, чем пишутся `DEVLOG.md` и `ROADMAP.md`.
80
81 Полноценный markdown здесь был бы зависимостью ради текста, который мы
82 сами и пишем по своим же правилам. Всё, что разбор не знает, остаётся
83 обычным абзацем — а не пропадает.
84 """
85 out: list[str] = []
86 for raw in re.split(r"\n{2,}", text.replace("\r\n", "\n")):
87 block = raw.strip("\n")
88 if not block.strip():
89 continue
90
91 heading = re.match(r"^(#{2,4})\s+(.*)$", block)
92 if heading:
93 level = min(len(heading.group(1)) + 1, 4)
94 out.append(f"<h{level}>{inline(heading.group(2))}</h{level}>")
95 continue
96
97 if re.match(r"^\s*[-*]\s+", block):
98 items = []
99 current: list[str] = []
100 for line in block.split("\n"):
101 if re.match(r"^\s*[-*]\s+", line):
102 if current:
103 items.append(" ".join(current))
104 current = [re.sub(r"^\s*[-*]\s+", "", line).strip()]
105 elif current:
106 # Продолжение пункта с переносом — частый вид в наших
107 # документах; без склейки оно превращалось бы в мусорный
108 # хвост отдельным пунктом.
109 current.append(line.strip())
110 if current:
111 items.append(" ".join(current))
112 body = "".join(f"<li>{inline(item)}</li>" for item in items if item)
113 out.append(f"<ul>{body}</ul>")
114 continue
115
116 out.append(f"<p>{inline(' '.join(line.strip() for line in block.split(chr(10))))}</p>")
117 return "\n".join(out)
118
119
120def inline(text: str) -> str:
121 escaped = html.escape(text, quote=False)
122 escaped = re.sub(r"`([^`]+)`", r"<code>\1</code>", escaped)
123 escaped = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", escaped)
124 escaped = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'<a href="\2">\1</a>', escaped)
125 return escaped
126
127
128def devlog_html() -> str:
129 text = (REPO / "DEVLOG.md").read_text(encoding="utf-8")
130 # Записи разделены строкой `## ` в начале строки; первый кусок — шапка
131 # самого файла, она на сайте не нужна.
132 parts = re.split(r"^## ", text, flags=re.M)[1:]
133 chunks = []
134 for part in parts[:DEVLOG_ENTRIES]:
135 title, _, body = part.partition("\n")
136 # `---` — разделитель записей в самом файле, на странице он лишний.
137 body = body.split("\n---\n")[0]
138 chunks.append(
139 f'<article class="ch-log"><div><h3>{inline(title.strip())}</h3>'
140 f"{markdown_to_html(body)}</div></article>"
141 )
142 return "\n".join(chunks)
143
144
145def roadmap_done_html() -> str:
146 text = (REPO / "ROADMAP.md").read_text(encoding="utf-8")
147 done = []
148 current: list[str] | None = None
149 for line in text.split("\n"):
150 if re.match(r"^\s*- \[x\]\s+", line):
151 if current:
152 done.append(" ".join(current))
153 current = [re.sub(r"^\s*- \[x\]\s+", "", line).strip()]
154 elif re.match(r"^\s*- \[ \]\s+", line) or re.match(r"^#{1,3} ", line):
155 if current:
156 done.append(" ".join(current))
157 current = None
158 elif current is not None and line.strip():
159 current.append(line.strip())
160 elif current:
161 done.append(" ".join(current))
162 current = None
163 if current:
164 done.append(" ".join(current))
165
166 if not done:
167 return '<p class="ch-note">Закрытых пунктов в дорожной карте не нашлось.</p>'
168 items = "".join(f"<li>{inline(item)}</li>" for item in done)
169 return f'<ul class="ch-ruled">{items}</ul>'
170
171
172# Какие файлы показывать в обозревателе исходников. Двоичное и служебное
173# туда не попадает: смотреть там нечего, а весить оно будет.
174SOURCE_EXTENSIONS = {
175 ".rs", ".toml", ".md", ".sh", ".py", ".json", ".css", ".html", ".svg",
176 ".desktop", ".manifest", ".lock", ".txt", ".yaml", ".yml",
177}
178
179# Файлы крупнее этого в обозреватель не кладём: `Cargo.lock` и подобные
180# читать в браузере всё равно никто не станет, а страница на мегабайт
181# текста открывается заметно дольше остальных.
182SOURCE_MAX_BYTES = 400_000
183
184
185def source_tree(out: pathlib.Path, template: str, ver: str) -> int:
186 """Раскладывает исходники репозитория страницами рядом с сайтом.
187
188 Зачем вообще: клонировать репозиторий ради того, чтобы заглянуть в один
189 файл, никто не станет — а «исходники открыты» без возможности их
190 посмотреть остаётся словами.
191
192 Подсветки синтаксиса здесь нет намеренно: правильная требует разбора
193 языка, а неправильная красит случайные слова и мешает читать. Номера
194 строк есть — по ним ссылаются.
195 """
196 import subprocess
197
198 listing = subprocess.run(
199 ["git", "ls-files", "-z"], cwd=REPO, capture_output=True, check=True
200 ).stdout.decode("utf-8")
201 files = [f for f in listing.split("\0") if f]
202
203 shown: list[tuple[str, int]] = []
204 for rel in files:
205 path = REPO / rel
206 if not path.is_file() or path.suffix.lower() not in SOURCE_EXTENSIONS:
207 continue
208 size = path.stat().st_size
209 if size > SOURCE_MAX_BYTES:
210 shown.append((rel, size))
211 continue
212 try:
213 text = path.read_text(encoding="utf-8")
214 except (UnicodeDecodeError, OSError):
215 continue
216
217 lines = text.split("\n")
218 # `.ch-listing` из системы сайта: номера строк рисует сама тема и
219 # мышью они не выделяются, поэтому скопированный кусок кода
220 # остаётся кодом.
221 # Классы `ln` и `src` — из `.ch-listing` в `system.css`: на них
222 # висят выравнивание номера, волосяная линейка между колонками и
223 # `user-select: none`, чтобы номера не попадали в скопированный
224 # код. Без них листинг рисуется, но номера копируются вместе с
225 # текстом.
226 numbered = "".join(
227 f'<tr id="L{n}"><td class="ln"><a href="#L{n}">{n}</a></td>'
228 f'<td class="src">{html.escape(line, quote=False) or " "}</td></tr>'
229 for n, line in enumerate(lines, 1)
230 )
231 body = (
232 '<section class="ch-sec"><div class="ch-wrap"><div class="ch-cols">'
233 '<div class="c-25 ch-aside">'
234 '<p class="ch-label"><a href="/launcher/source/">Исходники</a></p>'
235 f'<p class="ch-aside__note">{len(lines)} строк · {size // 1024 + 1} КиБ</p>'
236 '</div>'
237 '<div class="c-75 ch-main">'
238 f"<h2>{html.escape(rel)}</h2>"
239 f'<div class="ch-listing"><table>{numbered}</table></div>'
240 "</div></div></div></section>"
241 )
242 page = fill_template(template, title=rel, description=f"Исходный файл {rel}",
243 version=ver, body=body, active="source")
244 target = out / "src" / (rel + ".html")
245 target.parent.mkdir(parents=True, exist_ok=True)
246 target.write_text(page, encoding="utf-8")
247 shown.append((rel, size))
248
249 index_body = render_tree(shown)
250 page = fill_template(template, title="Дерево исходников",
251 description="Все файлы репозитория Chimera Launcher",
252 version=ver, body=index_body, active="source")
253 (out / "src").mkdir(parents=True, exist_ok=True)
254 (out / "src" / "index.html").write_text(page, encoding="utf-8")
255 return len(shown)
256
257
258def render_tree(files: list[tuple[str, int]]) -> str:
259 """Дерево файлов — `.ch-tree` из системы сайта.
260
261 Раньше каждый каталог был отдельным `h3`, и на пятидесяти каталогах
262 выходило пятьдесят заголовков одного уровня без единого `h2` над ними:
263 оглавление читало страницу как пятьдесят разделов, а глазу было негде
264 остановиться. Дерево — это дерево, и рисуется отступом.
265 """
266 groups: dict[str, list[tuple[str, int]]] = {}
267 for rel, size in files:
268 folder = str(pathlib.PurePosixPath(rel).parent)
269 groups.setdefault("." if folder == "." else folder, []).append((rel, size))
270
271 out = [
272 '<section class="ch-sec"><div class="ch-wrap"><div class="ch-cols">',
273 '<div class="c-66">',
274 '<a class="ch-back" href="/launcher/source/">К исходникам</a>',
275 '<p class="ch-eyebrow">Chimera Launcher</p><h1>Дерево исходников</h1>',
276 '<p class="ch-lead">Все файлы репозитория. Крупные лежат только в '
277 "клоне: читать <code>Cargo.lock</code> в браузере незачем.</p>",
278 "</div></div></div></section>",
279 '<section class="ch-sec"><div class="ch-wrap"><div class="ch-cols">',
280 '<div class="c-25 ch-aside">',
281 '<p class="ch-label">Дерево</p>',
282 f'<p class="ch-aside__note">файлов: {len(files)}, каталогов: {len(groups)}</p>',
283 "</div>",
284 '<div class="c-75 ch-main"><div class="ch-tree"><ul>',
285 ]
286 for folder in sorted(groups):
287 подпись = "корень репозитория" if folder == "." else html.escape(folder)
288 out.append(f'<li class="dir"><a href="#">{подпись}</a><ul>')
289 for rel, size in sorted(groups[folder]):
290 name = pathlib.PurePosixPath(rel).name
291 big = size > SOURCE_MAX_BYTES
292 cell = (
293 f"<span>{html.escape(name)} — только в клоне</span>"
294 if big
295 else f'<a href="/launcher/src/{rel}.html">{html.escape(name)}</a>'
296 )
297 out.append(f'<li>{cell}<span class="size">{size // 1024 + 1} КиБ</span></li>')
298 out.append("</ul></li>")
299 out.append("</ul></div></div></div></div></section>")
300 return "\n".join(out)
301
302
303def fill_template(template: str, *, title: str, description: str, version: str,
304 body: str, active: str) -> str:
305 text = template
306 text = text.replace("{{title}}", html.escape(title, quote=True))
307 text = text.replace("{{description}}", html.escape(description, quote=True))
308 text = text.replace("{{version}}", version)
309 text = text.replace("{{style_v}}", style_v())
310 text = text.replace("{{body}}", body)
311 for nav in PAGES:
312 text = text.replace("{{nav_" + nav + "}}", ' aria-current="page"' if nav == active else "")
313 return text
314
315
316def build() -> None:
317 template = (HERE / "template.html").read_text(encoding="utf-8")
318 ver = version()
319
320 if OUT.exists():
321 shutil.rmtree(OUT)
322 OUT.mkdir(parents=True)
323
324 generated = {"devlog": devlog_html(), "roadmap_done": roadmap_done_html()}
325
326 for page_id, (source, title, description) in PAGES.items():
327 body = (HERE / "pages" / source).read_text(encoding="utf-8")
328 for name, value in generated.items():
329 body = body.replace("{{" + name + "}}", value)
330 body = body.replace("{{version}}", ver)
331
332 html_text = template
333 html_text = html_text.replace("{{title}}", title)
334 html_text = html_text.replace("{{description}}", description)
335 html_text = html_text.replace("{{version}}", ver)
336 html_text = html_text.replace("{{style_v}}", style_v())
337 html_text = html_text.replace("{{body}}", body)
338 for nav in PAGES:
339 # `aria-current` — не украшение: без него активный пункт видно
340 # только по цвету, а читалке экрана не видно вовсе.
341 marker = ' aria-current="page"' if nav == page_id else ""
342 html_text = html_text.replace("{{nav_" + nav + "}}", marker)
343
344 left = re.findall(r"\{\{(\w+)\}\}", html_text)
345 if left:
346 raise SystemExit(f"в {page_id} остались неподставленные метки: {sorted(set(left))}")
347
348 target = OUT / "index.html" if page_id == "index" else OUT / page_id / "index.html"
349 target.parent.mkdir(parents=True, exist_ok=True)
350 target.write_text(html_text, encoding="utf-8")
351 print(f" {page_id}: {target.relative_to(OUT)} — {len(html_text) // 1024} КиБ")
352
353 shutil.copy(HERE / "style.css", OUT / "style.css")
354 shutil.copytree(HERE / "shots", OUT / "shots")
355 print(f" style.css и {len(list((OUT / 'shots').iterdir()))} снимков")
356
357 count = source_tree(OUT, template, ver)
358 print(f" обозреватель исходников: {count} файлов")
359
360
361def check_markup() -> None:
362 """Незакрытые теги ловим до выкладки, а не глазами на живой странице."""
363 import html.parser
364
365 class Check(html.parser.HTMLParser):
366 VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input",
367 "link", "meta", "source", "track", "wbr"}
368
369 def __init__(self) -> None:
370 super().__init__(convert_charrefs=True)
371 self.stack: list[tuple[str, int]] = []
372 self.problems: list[str] = []
373 # Уровни заголовков в порядке появления — для проверки ниже.
374 self.headings: list[tuple[int, int]] = []
375
376 def handle_starttag(self, tag, attrs):
377 if len(tag) == 2 and tag[0] == "h" and tag[1] in "123456":
378 self.headings.append((int(tag[1]), self.getpos()[0]))
379 if tag not in self.VOID:
380 self.stack.append((tag, self.getpos()[0]))
381
382 def handle_endtag(self, tag):
383 if tag in self.VOID:
384 return
385 if not self.stack:
386 self.problems.append(f"</{tag}> без открывающего, строка {self.getpos()[0]}")
387 return
388 open_tag, line = self.stack.pop()
389 if open_tag != tag:
390 self.problems.append(
391 f"<{open_tag}> со строки {line} закрыт как </{tag}> "
392 f"на строке {self.getpos()[0]}"
393 )
394
395 bad = 0
396 for path in sorted(OUT.rglob("*.html")):
397 check = Check()
398 check.feed(path.read_text(encoding="utf-8"))
399 problems = check.problems + [f"<{t}> со строки {l} не закрыт" for t, l in check.stack]
400
401 # Скачок через уровень заголовка. Нашлось 15.09 на `/launcher/db/`:
402 # подписи колонок подвала были `h4`, а последний заголовок страницы
403 # — `h2`, то есть документ перескакивал через `h3`. Глазами этого не
404 # видно вообще: подписи выглядят правильно, ломается оглавление и
405 # порядок обхода для программ чтения с экрана.
406 #
407 # Соблазн лечить это на вид — поставить тег по кеглю — и есть
408 # причина, по которой дефект живёт долго. Уровень отвечает за
409 # порядок документа, вид задаёт правило CSS.
410 levels = check.headings
411 problems += [
412 f"заголовок h{levels[i][0]} на строке {levels[i][1]} идёт после "
413 f"h{levels[i - 1][0]} — уровень пропущен"
414 for i in range(1, len(levels))
415 if levels[i][0] > levels[i - 1][0] + 1
416 ]
417 if problems:
418 bad += 1
419 print(f" {path.relative_to(OUT)}:")
420 for problem in problems:
421 print(f" {problem}")
422 # Несделанные подстановки. Замен две независимые ветки — обычные
423 # страницы и обозреватель исходников — и добавить поле в шаблон, забыв
424 # одну из них, ничего не ломает на вид: `{{style_v}}` уезжает на живую
425 # страницу как есть, а браузер молча считает это частью адреса.
426 # Существовавшая проверка в сборке смотрит только обычные страницы,
427 # а 269 страниц обозревателя пропускала — это проверено на отказ.
428 #
429 # Ячейки `<td class="src">` из проверки вычеркиваются: обозреватель
430 # печатает исходники проекта, а в `template.html`, `build.py` и
431 # разборе вики метки шаблонов лежат законно, как текст. Без этого
432 # сторож срабатывал на шести страницах и не пускал выкладку.
433 for path in sorted(OUT.rglob("*.html")):
434 text = re.sub(r'<td class="src">.*?</td>', "", path.read_text(encoding="utf-8"))
435 left = re.findall(r"\{\{[a-z_]+\}\}", text)
436 if left:
437 bad += 1
438 print(f" {path.relative_to(OUT)}: не подставлено {' '.join(sorted(set(left)))}")
439
440 if bad:
441 raise SystemExit("разметка сломана — не выкладываю")
442 print(" разметка в порядке")
443
444
445if __name__ == "__main__":
446 print("== сборка ==")
447 build()
448 print("== проверка разметки ==")
449 check_markup()
450 print(f"готово: {OUT}")
451 sys.exit(0)
452