emdg 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
emdg/__init__.py ADDED
@@ -0,0 +1,14 @@
1
+ from emdg.frontmatter import Frontmatter, parse_frontmatter
2
+ from emdg.generator import generate_html
3
+ from emdg.scanner import DocItem, DocSection, ScanResult, humanize_name, scan_docs
4
+
5
+ __all__ = [
6
+ "DocItem",
7
+ "DocSection",
8
+ "Frontmatter",
9
+ "ScanResult",
10
+ "generate_html",
11
+ "humanize_name",
12
+ "parse_frontmatter",
13
+ "scan_docs",
14
+ ]
emdg/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from emdg.cli import main
2
+
3
+ raise SystemExit(main())
emdg/cli.py ADDED
@@ -0,0 +1,147 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import logging
5
+ import os
6
+ import time
7
+ from functools import partial
8
+ from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
9
+ from pathlib import Path
10
+ from threading import Thread
11
+ from typing import Sequence
12
+
13
+ from emdg.generator import generate_html
14
+ from emdg.scanner import DEFAULT_IGNORE, scan_docs
15
+
16
+ LOGGER = logging.getLogger("emdg")
17
+ WATCH_INTERVAL = 0.5
18
+
19
+
20
+ def _arguments(argv: Sequence[str] | None = None) -> argparse.Namespace:
21
+ parser = argparse.ArgumentParser(
22
+ prog="emdg",
23
+ description="Build a single-page HTML site from Markdown files.",
24
+ )
25
+ parser.add_argument("source", nargs="?", default=".", help="Markdown source directory")
26
+ parser.add_argument("-o", "--output", default="docs.html", help="HTML output path")
27
+ parser.add_argument("-t", "--title", help="Site title")
28
+ parser.add_argument(
29
+ "-i",
30
+ "--ignore",
31
+ action="append",
32
+ default=[],
33
+ metavar="NAME",
34
+ help="Ignore a file or directory name (may be repeated)",
35
+ )
36
+ parser.add_argument(
37
+ "--theme", choices=("auto", "light", "dark"), default="auto", help="Initial theme"
38
+ )
39
+ parser.add_argument("--serve", action="store_true", help="Serve the generated site locally")
40
+ parser.add_argument("--watch", action="store_true", help="Rebuild when Markdown files change")
41
+ parser.add_argument("-v", "--verbose", action="count", default=0, help="Increase output")
42
+ return parser.parse_args(argv)
43
+
44
+
45
+ def _source_snapshot(source: Path, ignore: set[str]) -> tuple[tuple[str, int, int], ...]:
46
+ files: list[tuple[str, int, int]] = []
47
+ for current, directories, filenames in os.walk(source):
48
+ directories[:] = sorted(
49
+ name for name in directories if name not in ignore and not name.startswith(".")
50
+ )
51
+ for filename in filenames:
52
+ path = Path(current, filename)
53
+ if filename.startswith(".") or path.suffix.lower() != ".md":
54
+ continue
55
+ if filename in ignore:
56
+ continue
57
+ stat = path.stat()
58
+ files.append((path.relative_to(source).as_posix(), stat.st_mtime_ns, stat.st_size))
59
+ return tuple(sorted(files))
60
+
61
+
62
+ def _watch(
63
+ source: Path,
64
+ output: Path,
65
+ title: str | None,
66
+ theme: str,
67
+ ignore: set[str],
68
+ ) -> None:
69
+ previous = _source_snapshot(source, ignore)
70
+ LOGGER.info("Watching %s for Markdown changes", source)
71
+ while True:
72
+ time.sleep(WATCH_INTERVAL)
73
+ current = _source_snapshot(source, ignore)
74
+ if current != previous:
75
+ generate_html(scan_docs(source, ignore=ignore), output, title=title, theme=theme)
76
+ LOGGER.info("Rebuilt %s", output)
77
+ previous = current
78
+
79
+
80
+ def _serve(
81
+ output: Path,
82
+ watch: bool,
83
+ source: Path,
84
+ title: str | None,
85
+ theme: str,
86
+ ignore: set[str],
87
+ ) -> None:
88
+ handler = partial(SimpleHTTPRequestHandler, directory=str(output.parent))
89
+ server = ThreadingHTTPServer(("127.0.0.1", 8000), handler)
90
+ LOGGER.info("Serving %s at http://127.0.0.1:8000/%s", output.name, output.name)
91
+
92
+ if not watch:
93
+ try:
94
+ server.serve_forever()
95
+ except KeyboardInterrupt:
96
+ pass
97
+ finally:
98
+ server.server_close()
99
+ return
100
+
101
+ server_thread = Thread(target=server.serve_forever, daemon=True)
102
+ server_thread.start()
103
+ try:
104
+ _watch(source, output, title, theme, ignore)
105
+ except KeyboardInterrupt:
106
+ pass
107
+ finally:
108
+ server.shutdown()
109
+ server.server_close()
110
+ server_thread.join()
111
+
112
+
113
+ def main(argv: Sequence[str] | None = None) -> int:
114
+ args = _arguments(argv)
115
+ logging.basicConfig(
116
+ level=(
117
+ logging.DEBUG
118
+ if args.verbose > 1
119
+ else logging.INFO
120
+ if args.verbose
121
+ else logging.WARNING
122
+ ),
123
+ format="%(levelname)s: %(message)s",
124
+ )
125
+ source = Path(args.source).resolve()
126
+ output = Path(args.output).resolve()
127
+ ignore = set(DEFAULT_IGNORE).union(args.ignore)
128
+
129
+ try:
130
+ result = scan_docs(source, ignore=ignore)
131
+ output = generate_html(result, output, title=args.title, theme=args.theme)
132
+ except OSError as exc:
133
+ raise SystemExit(f"emdg: {exc}") from exc
134
+
135
+ LOGGER.info("Generated %s", output)
136
+ if args.serve:
137
+ _serve(output, args.watch, source, args.title, args.theme, ignore)
138
+ elif args.watch:
139
+ try:
140
+ _watch(source, output, args.title, args.theme, ignore)
141
+ except KeyboardInterrupt:
142
+ pass
143
+ return 0
144
+
145
+
146
+ if __name__ == "__main__":
147
+ raise SystemExit(main())
emdg/frontmatter.py ADDED
@@ -0,0 +1,121 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass, field
4
+
5
+
6
+ @dataclass(slots=True)
7
+ class Frontmatter:
8
+ title: str | None = None
9
+ emoji: str | None = None
10
+ order: int = 999
11
+ description: str | None = None
12
+ draft: bool = False
13
+ tags: list[str] = field(default_factory=list)
14
+ extra: dict[str, str] = field(default_factory=dict)
15
+
16
+ def _strip_quotes(value: str) -> str:
17
+ value = value.strip()
18
+ if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
19
+ return value[1:-1]
20
+ return value
21
+
22
+
23
+ def _parse_bool(value: str) -> bool:
24
+ return value.strip().lower() in {"true", "yes", "1", "on"}
25
+
26
+
27
+ def _parse_tags(raw: str) -> list[str]:
28
+ raw = raw.strip()
29
+ if raw.startswith("[") and raw.endswith("]"):
30
+ inner = raw[1:-1].strip()
31
+ if not inner:
32
+ return []
33
+ parts: list[str] = []
34
+ current: list[str] = []
35
+ quote: str | None = None
36
+ for char in inner:
37
+ if char in {"'", '"'}:
38
+ if quote == char:
39
+ quote = None
40
+ elif quote is None:
41
+ quote = char
42
+ if char == "," and quote is None:
43
+ part = "".join(current).strip()
44
+ if part:
45
+ parts.append(_strip_quotes(part))
46
+ current = []
47
+ else:
48
+ current.append(char)
49
+ part = "".join(current).strip()
50
+ if part:
51
+ parts.append(_strip_quotes(part))
52
+ return parts
53
+ return [_strip_quotes(raw)] if raw else []
54
+
55
+
56
+ def parse_frontmatter(content: str) -> tuple[Frontmatter, str]:
57
+ """
58
+ Extract YAML-like frontmatter from Markdown content.
59
+
60
+ Returns (Frontmatter, body_without_frontmatter).
61
+ """
62
+ lines = content.splitlines(keepends=True)
63
+ if not lines or lines[0].strip() != "---":
64
+ return Frontmatter(), content
65
+
66
+ end_idx: int | None = None
67
+ for idx in range(1, len(lines)):
68
+ if lines[idx].strip() in {"---", "..."}:
69
+ end_idx = idx
70
+ break
71
+
72
+ if end_idx is None:
73
+ return Frontmatter(), content
74
+
75
+ fm_lines = lines[1:end_idx]
76
+ body = "".join(lines[end_idx + 1 :]).lstrip("\r\n")
77
+
78
+ meta = Frontmatter()
79
+ current_list_key: str | None = None
80
+
81
+ for raw_line in fm_lines:
82
+ stripped = raw_line.strip()
83
+ if not stripped or stripped.startswith("#"):
84
+ continue
85
+
86
+ if current_list_key and stripped.startswith("- "):
87
+ item = _strip_quotes(stripped[2:])
88
+ if current_list_key == "tags" and item:
89
+ meta.tags.append(item)
90
+ continue
91
+
92
+ current_list_key = None
93
+ if ":" not in raw_line:
94
+ continue
95
+
96
+ key, raw_val = raw_line.split(":", 1)
97
+ key = key.strip().lower()
98
+ val = raw_val.strip()
99
+
100
+ if key == "title" and val:
101
+ meta.title = _strip_quotes(val)
102
+ elif key == "emoji" and val:
103
+ meta.emoji = _strip_quotes(val)
104
+ elif key == "order" and val:
105
+ try:
106
+ meta.order = int(_strip_quotes(val))
107
+ except ValueError:
108
+ pass
109
+ elif key == "description" and val:
110
+ meta.description = _strip_quotes(val)
111
+ elif key == "draft" and val:
112
+ meta.draft = _parse_bool(_strip_quotes(val))
113
+ elif key == "tags":
114
+ if val:
115
+ meta.tags = _parse_tags(val)
116
+ else:
117
+ current_list_key = "tags"
118
+ else:
119
+ meta.extra[key] = _strip_quotes(val)
120
+
121
+ return meta, body