k-synth/docs-build.py at main · octetta/k-synth · 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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
#!/usr/bin/env python3
"""
docs-build.py — convert guide.md and readme.md to HTML using the doc-template.

Uses pandoc if available, otherwise falls back to the 'markdown' Python package.
Install the fallback with: pip install markdown

Usage: python3 docs-build.py
Output: guide.html, readme.html
"""

import sys
import os
import subprocess
import re

TEMPLATE = 'doc-template.html'

DOCS = [
    {
        'src':   'api.md',
        'out':   'api.html',
        'title': 'ksynth — c API reference',
        'nav':   '<a class="doc-nav-btn" href="index.html">&#8592; app</a>'
                 '<a class="doc-nav-btn" href="reference.html">reference</a>'
                 '<a class="doc-nav-btn" href="guide.html">guide</a>'
                 '<a class="doc-nav-btn" href="readme.html">readme</a>'
    },

    {
        'src':   'reference.md',
        'out':   'reference.html',
        'title': 'ksynth — verb reference',
        'nav':   '<a class="doc-nav-btn" href="index.html">&#8592; app</a>'
                 '<a class="doc-nav-btn" href="guide.html">guide</a>'
                 '<a class="doc-nav-btn" href="readme.html">readme</a>'
                 '<a class="doc-nav-btn" href="api.html">api</a>'
    },

    {
        'src':   'guide.md',
        'out':   'guide.html',
        'title': 'ksynth web — user guide',
        'nav':   '<a class="doc-nav-btn" href="index.html">&#8592; app</a>'
                 '<a class="doc-nav-btn" href="reference.html">reference</a>'
                 '<a class="doc-nav-btn" href="readme.html">readme</a>'
                 '<a class="doc-nav-btn" href="api.html">api</a>'
    },
    {
        'src':   'readme.md',
        'out':   'readme.html',
        'title': 'ksynth — readme',
        'nav':   '<a class="doc-nav-btn" href="index.html">&#8592; app</a>'
                 '<a class="doc-nav-btn" href="guide.html">guide</a>'
                 '<a class="doc-nav-btn" href="reference.html">reference</a>'
                 '<a class="doc-nav-btn" href="api.html">api</a>'
    },
]


def md_to_html_pandoc(src):
    result = subprocess.run(
        ['pandoc', '-f', 'markdown', '-t', 'html', '--no-highlight', src],
        capture_output=True, text=True, check=True
    )
    return result.stdout


def md_to_html_python(src):
    try:
        import markdown
    except ImportError:
        print('ERROR: pandoc not found and "markdown" package not installed.')
        print('Install with: pip install markdown')
        sys.exit(1)
    with open(src) as f:
        text = f.read()
    return markdown.markdown(
        text,
        extensions=['fenced_code', 'tables', 'toc'],
        output_format='html'
    )


def convert(src):
    """Try pandoc first, fall back to python-markdown."""
    try:
        subprocess.run(['pandoc', '--version'], capture_output=True, check=True)
        return md_to_html_pandoc(src)
    except (subprocess.CalledProcessError, FileNotFoundError):
        return md_to_html_python(src)


def build(doc, template):
    body = convert(doc['src'])
    html = template
    html = html.replace('{{TITLE}}', doc['title'])
    html = html.replace('{{NAV}}',   doc['nav'])
    html = html.replace('{{BODY}}',  body)
    with open(doc['out'], 'w') as f:
        f.write(html)
    print(f"  {doc['src']} -> {doc['out']}")


def main():
    if not os.path.exists(TEMPLATE):
        print(f'ERROR: {TEMPLATE} not found')
        sys.exit(1)
    with open(TEMPLATE) as f:
        template = f.read()
    print('Building docs...')
    for doc in DOCS:
        build(doc, template)
    print('Done.')


if __name__ == '__main__':
    main()