|
| 1 | +"""Convert docs/*.md to docs/*.html.""" |
| 2 | + |
| 3 | +import pathlib |
| 4 | +import re |
| 5 | +import shutil |
| 6 | +import sys |
| 7 | +import markdown |
| 8 | + |
| 9 | +DOCS = pathlib.Path(__file__).parent |
| 10 | +ASSETS = DOCS / 'html' |
| 11 | +OUTPUT = pathlib.Path(sys.argv[1]) if len(sys.argv) > 1 else ASSETS |
| 12 | +VERSION = sys.argv[2] if len(sys.argv) > 2 else '' |
| 13 | + |
| 14 | +PAGES = [ |
| 15 | + ('index.html', 'Index'), |
| 16 | + ('intro.html', 'Introduction'), |
| 17 | + ('design.html', 'Design'), |
| 18 | + ('usage.html', 'Usage'), |
| 19 | + ('cmake.html', 'CMake'), |
| 20 | + ('reference.html', 'Reference'), |
| 21 | +] |
| 22 | + |
| 23 | +TEMPLATE = """\ |
| 24 | +<!DOCTYPE html> |
| 25 | +<html> |
| 26 | +<head> |
| 27 | + <meta charset="utf-8"> |
| 28 | + <title>{title}</title> |
| 29 | + <link rel="stylesheet" type="text/css" href="css/normalize.css"> |
| 30 | + <link rel="stylesheet" type="text/css" href="css/highlight.css"> |
| 31 | + <link rel="stylesheet" type="text/css" href="css/main.css"> |
| 32 | + <link rel="shortcut icon" href="css/img/favicon.png" |
| 33 | + type="image/png"> |
| 34 | +</head> |
| 35 | +<body> |
| 36 | + <div id="container"> |
| 37 | + <header id="head"> |
| 38 | + <div class="top"> |
| 39 | + <img src="logo.png" class="logo" alt=""> |
| 40 | + <a href="index.html">Eggs.Stacktrace</a> |
| 41 | + </div> |
| 42 | + </header> |
| 43 | + <div id="head_post"> |
| 44 | +{text_nav} |
| 45 | + </div> |
| 46 | + <div class="{page_class}"> |
| 47 | + <section> |
| 48 | +{body} |
| 49 | + </section> |
| 50 | + </div> |
| 51 | + <hr> |
| 52 | + <p> |
| 53 | + Copyright © 2026 Agustin Berge |
| 54 | + </p> |
| 55 | + <p> |
| 56 | + Distributed under the Boost Software License, Version 1.0.<br> |
| 57 | + See accompanying file LICENSE.txt or copy at |
| 58 | + <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a> |
| 59 | + </p> |
| 60 | + </div> |
| 61 | +</body> |
| 62 | +</html> |
| 63 | +""" |
| 64 | + |
| 65 | +def build_text_nav(current_href): |
| 66 | + items = [] |
| 67 | + for href, label in PAGES[1:]: # skip index (already the logo link) |
| 68 | + cls = 'name title' if href == current_href else 'name' |
| 69 | + items.append( |
| 70 | + f' <a class="{cls}" href="{href}">{label}</a>') |
| 71 | + return ' ·\n'.join(items) |
| 72 | + |
| 73 | +def strip_html_comment(text): |
| 74 | + return re.sub(r'^\s*<!--.*?-->\s*', '', text, flags=re.DOTALL) |
| 75 | + |
| 76 | +def add_heading_anchors(html): |
| 77 | + """Wrap heading text in a self-link so headings are blue/clickable.""" |
| 78 | + def replace(m): |
| 79 | + tag, attrs, content = m.group(1), m.group(2), m.group(3) |
| 80 | + id_match = re.search(r'\bid="([^"]+)"', attrs) |
| 81 | + if not id_match: |
| 82 | + return m.group(0) |
| 83 | + hid = id_match.group(1) |
| 84 | + return (f'<{tag}{attrs}>' |
| 85 | + f'<a href="#{hid}">{content}</a>' |
| 86 | + f'</{tag}>') |
| 87 | + return re.sub( |
| 88 | + r'<(h[1-6])( [^>]+)>(.*?)</\1>', |
| 89 | + replace, html, flags=re.DOTALL) |
| 90 | + |
| 91 | +def md_to_html(src): |
| 92 | + src = strip_html_comment(src) |
| 93 | + src = re.sub( |
| 94 | + r'\[([^\]]+)\]\(([^)]+)\.md\)', r'[\1](\2.html)', src) |
| 95 | + md = markdown.Markdown( |
| 96 | + extensions=['tables', 'fenced_code', 'codehilite', 'toc'], |
| 97 | + extension_configs={ |
| 98 | + 'codehilite': {'guess_lang': False}, |
| 99 | + }) |
| 100 | + return add_heading_anchors(md.convert(src)) |
| 101 | + |
| 102 | +def build(): |
| 103 | + OUTPUT.mkdir(parents=True, exist_ok=True) |
| 104 | + if OUTPUT != ASSETS: |
| 105 | + shutil.copytree(ASSETS / 'css', OUTPUT / 'css', dirs_exist_ok=True) |
| 106 | + shutil.copy2(ASSETS / 'logo.png', OUTPUT / 'logo.png') |
| 107 | + by_stem = {pathlib.Path(h).stem: l for h, l in PAGES} |
| 108 | + for md_path in sorted(DOCS.glob('*.md')): |
| 109 | + stem = md_path.stem |
| 110 | + html_name = stem + '.html' |
| 111 | + src = md_path.read_text(encoding='utf-8-sig') |
| 112 | + if VERSION: |
| 113 | + src = src.replace('@VERSION@', VERSION) |
| 114 | + body = md_to_html(src) |
| 115 | + label = by_stem.get(stem, stem) |
| 116 | + title = f'{label} - Eggs.Stacktrace' |
| 117 | + html = TEMPLATE.format( |
| 118 | + title=title, |
| 119 | + text_nav=build_text_nav(html_name), |
| 120 | + page_class=stem, |
| 121 | + body=body, |
| 122 | + ) |
| 123 | + (OUTPUT / html_name).write_text(html, encoding='utf-8') |
| 124 | + print(f' {html_name}') |
| 125 | + |
| 126 | +if __name__ == '__main__': |
| 127 | + build() |
| 128 | + print('done') |
0 commit comments