Debian Codegraph @

subprojects/meson-docs/docs/refman/generatorman.py

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 import re
2 from pathlib import Path
3
4 from .generatorbase import GeneratorBase
5 from .model import (
6 ReferenceManual,
7 Function,
8 Object,
9 PosArg,
10 VarArgs,
11 Kwarg,
12 )
13
14 import typing as T
15
16
17 class ManPage:
18 def __init__(self, path: Path):
19 self.path = path
20 self.text = ""
21
22 def reset_font(self) -> None:
23 self.text += ".P\n"
24
25 def title(self, name: str, section: int) -> None:
26 import datetime
27
28 date = datetime.date.today()
29 self.reset_font()
30 self.text += f'.TH "{name}" "{section}" "{date}"\n'
31
32 def section(self, name: str) -> None:
33 self.reset_font()
34 self.text += f".SH {name}\n"
35
36 def subsection(self, name: str) -> None:
37 self.reset_font()
38 self.text += f".SS {name}\n"
39
40 def par(self, text: str) -> None:
41 self.reset_font()
42 self.text += f"{text}\n"
43
44 def indent(self, amount: int = 4) -> None:
45 self.text += f".RS {amount}\n"
46
47 def unindent(self) -> None:
48 self.text += ".RE\n"
49
50 def br(self) -> None:
51 self.text += ".br\n"
52
53 def nl(self) -> None:
54 self.text += "\n"
55
56 def line(self, text: str) -> None:
57 if text and text[0] in [".", "'"]:
58 self.text += "\\"
59 self.text += f"{text}\n"
60
61 def inline(self, text: str) -> None:
62 self.text += f"{text}"
63
64 def write(self) -> None:
65 self.path.write_text(self.text, encoding="utf-8")
66
67 @staticmethod
68 def bold(text: str) -> str:
69 return f"\\fB{text}\\fR"
70
71 @staticmethod
72 def italic(text: str) -> str:
73 return f"\\fI{text}\\fR"
74
75
76 class GeneratorMan(GeneratorBase):
77 def __init__(
78 self, manual: ReferenceManual, out: Path, enable_modules: bool
79 ) -> None:
80 super().__init__(manual)
81 self.out = out
82 self.enable_modules = enable_modules
83 self.links: T.List[str] = []
84
85 def generate_description(self, page: ManPage, desc: str) -> None:
86 def italicise(match: T.Match[str]) -> str:
87 v = match.group(1)
88 if v[0] == "@":
89 v = v[1:]
90
91 return ManPage.italic(v)
92
93 desc = re.sub(re.compile(r"\[\[(.*?)\]\]", re.DOTALL), italicise, desc)
94
95 def linkify(match: T.Match[str]) -> str:
96 replacement = ManPage.italic(match.group(1))
97
98 if match.group(2)[0] != "#":
99 if match.group(2) in self.links:
100 num = self.links.index(match.group(2))
101 else:
102 self.links.append(match.group(2))
103 num = len(self.links)
104
105 replacement += f"[{num}]"
106
107 return replacement
108
109 desc = re.sub(re.compile(r"\[(.*?)\]\((.*?)\)", re.DOTALL), linkify, desc)
110
111 def bold(match: T.Match[str]) -> str:
112 return ManPage.bold(match.group(1))
113
114 desc = re.sub(re.compile(r"\*(.*?)\*"), bold, desc)
115
116 isCode = False
117 for chunk in desc.split("```"):
118 if isCode:
119 page.indent()
120 lines = chunk.strip().split("\n")
121 if lines[0] == "meson":
122 lines = lines[1:]
123
124 for line in lines:
125 page.line(line)
126 page.br()
127 page.unindent()
128 else:
129 inList = False
130 for line in chunk.strip().split("\n"):
131 if len(line) == 0:
132 page.nl()
133 if inList:
134 page.nl()
135 inList = False
136 elif line[0:2] in ["- ", "* "]:
137 if inList:
138 page.nl()
139 page.br()
140 else:
141 inList = True
142
143 page.inline(line.strip() + " ")
144 elif inList and line[0] == " ":
145 page.inline(line.strip() + " ")
146 else:
147 inList = False
148 page.line(line)
149
150 if inList:
151 page.nl()
152
153 isCode = not isCode
154
155 def function_name(self, f: Function, o: Object = None) -> str:
156 name = ""
157 if o is not None:
158 name += f"{o.name}."
159
160 name += f.name
161 return name
162
163 def generate_function_signature(
164 self, page: ManPage, f: Function, o: Object = None
165 ) -> None:
166 args = []
167
168 if f.posargs:
169 args += [arg.name for arg in f.posargs]
170
171 if f.varargs:
172 args += [f.varargs.name + "..."]
173
174 if f.optargs:
175 args += [f"[{arg.name}]" for arg in f.optargs]
176
177 for kwarg in self.sorted_and_filtered(list(f.kwargs.values())):
178 kw = kwarg.name + ":"
179 if kwarg.default:
180 kw += " " + ManPage.bold(kwarg.default)
181 args += [kw]
182
183 ret = ManPage.italic(f.returns.raw) + " "
184
185 prefix = f"{ret}{self.function_name(f, o)}("
186 sig = ", ".join(args)
187 suffix = ")"
188
189 if len(prefix) + len(sig) + len(suffix) > 70:
190 page.line(prefix)
191 page.br()
192 page.indent()
193 for arg in args:
194 page.line(arg + ",")
195 page.br()
196 page.unindent()
197 page.line(suffix)
198 else:
199 page.line(prefix + sig + suffix)
200
201 def base_info(
202 self, x: T.Union[PosArg, VarArgs, Kwarg, Function, Object]
203 ) -> T.List[str]:
204 info = []
205 if x.deprecated:
206 info += [ManPage.bold("deprecated") + f" since {x.deprecated}"]
207 if x.since:
208 info += [f"since {x.since}"]
209
210 return info
211
212 def generate_function_arg(
213 self,
214 page: ManPage,
215 arg: T.Union[PosArg, VarArgs, Kwarg],
216 isOptarg: bool = False,
217 ) -> None:
218 required = (
219 arg.required
220 if isinstance(arg, Kwarg)
221 else not isOptarg and not isinstance(arg, VarArgs)
222 )
223
224 page.line(ManPage.bold(arg.name))
225
226 info = [ManPage.italic(arg.type.raw)]
227
228 if required:
229 info += [ManPage.bold("required")]
230 if isinstance(arg, (PosArg, Kwarg)) and arg.default:
231 info += [f"default: {arg.default}"]
232 if isinstance(arg, VarArgs):
233 mn = 0 if arg.min_varargs < 0 else arg.min_varargs
234 mx = "N" if arg.max_varargs < 0 else arg.max_varargs
235 info += [f"{mn}...{mx} times"]
236
237 info += self.base_info(arg)
238
239 page.line(", ".join(info))
240
241 page.br()
242 page.indent(2)
243 self.generate_description(page, arg.description.strip())
244 page.unindent()
245 page.nl()
246
247 def generate_function_argument_section(
248 self,
249 page: ManPage,
250 name: str,
251 args: T.Sequence[T.Union[PosArg, VarArgs, Kwarg]],
252 isOptarg: bool = False,
253 ) -> None:
254 if not args:
255 return
256
257 page.line(ManPage.bold(name))
258 page.indent()
259 for arg in args:
260 self.generate_function_arg(page, arg, isOptarg)
261 page.unindent()
262
263 def generate_sub_sub_section(
264 self, page: ManPage, name: str, text: T.List[str], process: bool = True
265 ) -> None:
266 page.line(ManPage.bold(name))
267 page.indent()
268 if process:
269 for line in text:
270 self.generate_description(page, line.strip())
271 else:
272 page.line("\n\n".join([line.strip() for line in text]))
273 page.unindent()
274
275 def generate_function(self, page: ManPage, f: Function, obj: Object = None) -> None:
276 page.subsection(self.function_name(f, obj) + "()")
277 page.indent(0)
278
279 page.line(ManPage.bold("SYNOPSIS"))
280 page.indent()
281 self.generate_function_signature(page, f, obj)
282
283 info = self.base_info(f)
284 if info:
285 page.nl()
286 page.line(", ".join(info))
287 page.unindent()
288 page.nl()
289
290 self.generate_sub_sub_section(page, "DESCRIPTION", [f.description])
291 page.nl()
292
293 self.generate_function_argument_section(page, "POSARGS", f.posargs)
294 if f.varargs:
295 self.generate_function_argument_section(page, "VARARGS", [f.varargs])
296 self.generate_function_argument_section(page, "OPTARGS", f.optargs, True)
297 self.generate_function_argument_section(
298 page, "KWARGS", self.sorted_and_filtered(list(f.kwargs.values()))
299 )
300
301 if f.notes:
302 self.generate_sub_sub_section(page, "NOTES", f.notes)
303 if f.warnings:
304 self.generate_sub_sub_section(page, "WARNINGS", f.warnings)
305 if f.example:
306 self.generate_sub_sub_section(page, "EXAMPLE", [f.example])
307
308 page.unindent()
309
310 def generate_object(self, page: ManPage, obj: Object) -> None:
311 page.subsection(obj.name)
312 page.indent(2)
313
314 info = self.base_info(obj)
315 if info:
316 page.line(", ".join(info))
317 page.br()
318
319 if obj.extends:
320 page.line(ManPage.bold("extends: ") + obj.extends)
321 page.br()
322
323 ret = [x.name for x in self.sorted_and_filtered(obj.returned_by)]
324 if ret:
325 page.line(ManPage.bold("returned_by: ") + ", ".join(ret))
326 page.br()
327
328 ext = [x.name for x in self.sorted_and_filtered(obj.extended_by)]
329 if ext:
330 page.line(ManPage.bold("extended_by: ") + ", ".join(ext))
331 page.br()
332
333 page.nl()
334
335 self.generate_description(page, obj.description.strip())
336 page.nl()
337
338 if obj.notes:
339 self.generate_sub_sub_section(page, "NOTES", obj.notes)
340 if obj.warnings:
341 self.generate_sub_sub_section(page, "WARNINGS", obj.warnings)
342 if obj.example:
343 self.generate_sub_sub_section(page, "EXAMPLE", [obj.example])
344
345 page.unindent()
346
347 def generate(self) -> None:
348 page = ManPage(self.out)
349
350 page.title("meson-reference", 3)
351
352 page.section("NAME")
353 page.par(
354 f"meson-reference v{self._extract_meson_version()}"
355 + " - a reference for meson functions and objects"
356 )
357
358 page.section("DESCRIPTION")
359 self.generate_description(
360 page,
361 """This manual is divided into two sections, *FUNCTIONS* and *OBJECTS*. *FUNCTIONS* contains a reference for all meson functions and methods. Methods are denoted by [[object_name]].[[method_name]](). *OBJECTS* contains additional information about each object.""",
362 )
363
364 page.section("FUNCTIONS")
365 for f in self.sorted_and_filtered(self.functions):
366 self.generate_function(page, f)
367
368 for obj in self.sorted_and_filtered(self.objects):
369 for f in self.sorted_and_filtered(obj.methods):
370 self.generate_function(page, f, obj)
371
372 page.section("OBJECTS")
373 for obj in self.sorted_and_filtered(self.objects):
374 self.generate_object(page, obj)
375
376 page.section("SEE ALSO")
377 for i in range(len(self.links)):
378 link = self.links[i]
379 page.line(f"[{i + 1}] {link}")
380 page.br()
381
382 page.section("COPYRIGHT")
383 page.par("Documentation comes from the meson project (https://mesonbuild.com) "
384 + "and is released under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). "
385 + "Code samples are released under CC0 1.0 Universal (CC0 1.0).")
386 page.par("Meson is a registered trademark of Jussi Pakkanen.")
387
388 page.write()