Debian Codegraph @

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

raw
1 # SPDX-License-Identifier: Apache-2.0
2 # Copyright 2021 The Meson development team
3
4 from .generatorbase import GeneratorBase
5 import re
6 import json
7
8 from .model import (
9 ReferenceManual,
10 Function,
11 Method,
12 Object,
13 ObjectType,
14 Type,
15 DataTypeInfo,
16 ArgBase,
17 PosArg,
18 VarArgs,
19 Kwarg,
20 )
21
22 from pathlib import Path
23 from textwrap import dedent
24 import typing as T
25
26 from mesonbuild import mlog
27
28 PlaceholderTypes = T.Union[None, str, bool]
29 FunctionDictType = T.Dict[
30 str,
31 T.Union[
32 PlaceholderTypes,
33 T.Dict[str, PlaceholderTypes],
34 T.Dict[str, T.Dict[str, PlaceholderTypes]],
35 T.Dict[str, T.List[T.Dict[str, PlaceholderTypes]]],
36 T.List[T.Dict[str, PlaceholderTypes]],
37 T.List[str],
38 ]
39 ]
40
41 _ROOT_BASENAME = 'Reference-manual'
42
43 _OBJ_ID_MAP = {
44 ObjectType.ELEMENTARY: 'elementary',
45 ObjectType.BUILTIN: 'builtin',
46 ObjectType.MODULE: 'module',
47 ObjectType.RETURNED: 'returned',
48 }
49
50 # Indent all but the first line with 4*depth spaces.
51 # This function is designed to be used with `dedent`
52 # and fstrings where multiline strings are used during
53 # the string interpolation.
54 def smart_indent(raw: str, depth: int = 3) -> str:
55 lines = raw.split('\n')
56 first_line = lines[0]
57 lines = [' ' * (4 * depth) + x for x in lines]
58 lines[0] = first_line # Do not indent the first line
59 return '\n'.join(lines)
60
61 def code_block(code: str) -> str:
62 code = dedent(code)
63 return f'<pre><code class="language-meson">{code}</code></pre>'
64
65 class GeneratorMD(GeneratorBase):
66 def __init__(self, manual: ReferenceManual, sitemap_out: Path, sitemap_in: Path, link_def_out: Path, enable_modules: bool) -> None:
67 super().__init__(manual)
68 self.sitemap_out = sitemap_out.resolve()
69 self.sitemap_in = sitemap_in.resolve()
70 self.link_def_out = link_def_out.resolve()
71 self.out_dir = self.sitemap_out.parent
72 self.enable_modules = enable_modules
73 self.generated_files: T.Dict[str, str] = {}
74
75 # Utility functions
76 def _gen_filename(self, file_id: str, *, extension: str = 'md') -> str:
77 parts = file_id.split('.')
78 assert parts[0] == 'root'
79 assert all([x for x in parts])
80 parts[0] = _ROOT_BASENAME
81 parts = [re.sub(r'[0-9]+_', '', x) for x in parts]
82 return f'{"_".join(parts)}.{extension}'
83
84 def _gen_object_file_id(self, obj: Object) -> str:
85 '''
86 Deterministically generate a unique file ID for the Object.
87
88 This ID determines where the object will be inserted in the sitemap.
89 '''
90 if obj.obj_type == ObjectType.RETURNED and obj.defined_by_module is not None:
91 base = self._gen_object_file_id(obj.defined_by_module)
92 return f'{base}.{obj.name}'
93 return f'root.{_OBJ_ID_MAP[obj.obj_type]}.{obj.name}'
94
95 def _link_to_object(self, obj: T.Union[Function, Object], in_code_block: bool = False) -> str:
96 '''
97 Generate a placeholder tag for the function/method/object documentation.
98 This tag is then replaced in the custom hotdoc plugin.
99 '''
100 prefix = '#' if in_code_block else ''
101 if isinstance(obj, Object):
102 return f'[[{prefix}@{obj.name}]]'
103 elif isinstance(obj, Method):
104 return f'[[{prefix}{obj.obj.name}.{obj.name}]]'
105 elif isinstance(obj, Function):
106 return f'[[{prefix}{obj.name}]]'
107 else:
108 raise RuntimeError(f'Invalid argument {obj}')
109
110 def _write_file(self, data: str, file_id: str) -> None:#
111 ''' Write the data to disk and store the id for the generated data '''
112
113 self.generated_files[file_id] = self._gen_filename(file_id)
114 out_file = self.out_dir / self.generated_files[file_id]
115 out_file.write_text(data, encoding='ascii')
116 mlog.log('Generated', mlog.bold(out_file.name))
117
118 def _write_template(self, data: T.Dict[str, T.Any], file_id: str, template_name: T.Optional[str] = None) -> None:
119 ''' Render the template mustache files and write the result '''
120 template_dir = Path(__file__).resolve().parent / 'templates'
121 template_name = template_name or file_id
122 template_name = f'{template_name}.mustache'
123 template_file = template_dir / template_name
124
125 # Import here, so that other generators don't also depend on it
126 import chevron
127 result = chevron.render(
128 template=template_file.read_text(encoding='utf-8'),
129 data=data,
130 partials_path=template_dir.as_posix(),
131 warn=True,
132 )
133
134 self._write_file(result, file_id)
135
136
137 # Actual generator functions
138 def _gen_func_or_method(self, func: Function) -> FunctionDictType:
139 def render_type(typ: Type, in_code_block: bool = False) -> str:
140 def data_type_to_str(dt: DataTypeInfo) -> str:
141 base = self._link_to_object(dt.data_type, in_code_block)
142 if dt.holds:
143 return f'{base}[{render_type(dt.holds, in_code_block)}]'
144 return base
145 assert typ.resolved
146 return ' | '.join([data_type_to_str(x) for x in typ.resolved])
147
148 def len_stripped(s: str) -> int:
149 s = s.replace(']]', '')
150 # I know, this regex is ugly but it works.
151 return len(re.sub(r'\[\[(#|@)*([^\[])', r'\2', s))
152
153 def arg_anchor(arg: ArgBase) -> str:
154 return f'{func.name}_{arg.name.replace("<", "_").replace(">", "_")}'
155
156 def render_signature() -> str:
157 # Skip a lot of computations if the function does not take any arguments
158 if not any([func.posargs, func.optargs, func.kwargs, func.varargs]):
159 return f'{render_type(func.returns, True)} {func.name}()'
160
161 signature = dedent(f'''\
162 # {self.brief(func)}
163 {render_type(func.returns, True)} {func.name}(
164 ''')
165
166 # Calculate maximum lengths of the type and name
167 all_args: T.List[ArgBase] = []
168 all_args += func.posargs
169 all_args += func.optargs
170 all_args += [func.varargs] if func.varargs else []
171
172 max_type_len = 0
173 max_name_len = 0
174 if all_args:
175 max_type_len = max([len_stripped(render_type(x.type)) for x in all_args])
176 max_name_len = max([len(x.name) for x in all_args])
177
178 # Generate some common strings
179 def prepare(arg: ArgBase, link: bool = True) -> T.Tuple[str, str, str, str]:
180 type_str = render_type(arg.type, True)
181 type_len = len_stripped(type_str)
182 type_space = ' ' * (max_type_len - type_len)
183 name_space = ' ' * (max_name_len - len(arg.name))
184 name_str = f'<b>{arg.name.replace("<", "&lt;").replace(">", "&gt;")}</b>'
185 if link:
186 name_str = f'<a href="#{arg_anchor(arg)}">{name_str}</a>'
187
188 return type_str, type_space, name_str, name_space
189
190 for i in func.posargs:
191 type_str, type_space, name_str, name_space = prepare(i)
192 signature += f' {type_str}{type_space} {name_str},{name_space} # {self.brief(i)}\n'
193
194 for i in func.optargs:
195 type_str, type_space, name_str, name_space = prepare(i)
196 signature += f' {type_str}{type_space} [{name_str}],{name_space} # {self.brief(i)}\n'
197
198 if func.varargs:
199 type_str, type_space, name_str, name_space = prepare(func.varargs, link=False)
200 signature += f' {type_str}{type_space} {name_str}...,{name_space} # {self.brief(func.varargs)}\n'
201
202 # Abort if there are no kwargs
203 if not func.kwargs:
204 return signature + ')'
205
206 # Only add this separator if there are any posargs
207 if all_args:
208 signature += '\n # Keyword arguments:\n'
209
210 # Recalculate lengths for kwargs
211 all_args = list(func.kwargs.values())
212 max_type_len = max([len_stripped(render_type(x.type)) for x in all_args])
213 max_name_len = max([len(x.name) for x in all_args])
214
215 for kwarg in self.sorted_and_filtered(list(func.kwargs.values())):
216 type_str, type_space, name_str, name_space = prepare(kwarg)
217 required = ' <i>[required]</i> ' if kwarg.required else ' '
218 required = required if any([x.required for x in func.kwargs.values()]) else ''
219 signature += f' {name_str}{name_space} : {type_str}{type_space} {required} # {self.brief(kwarg)}\n'
220
221 return signature + ')'
222
223 def gen_arg_data(arg: T.Union[PosArg, Kwarg, VarArgs], *, optional: bool = False) -> T.Dict[str, PlaceholderTypes]:
224 data: T.Dict[str, PlaceholderTypes] = {
225 'row-id': arg_anchor(arg),
226 'name': arg.name,
227 'type': render_type(arg.type),
228 'description': arg.description,
229 'since': arg.since or None,
230 'deprecated': arg.deprecated or None,
231 'optional': optional,
232 'default': None,
233 }
234
235 if isinstance(arg, VarArgs):
236 data.update({
237 'min': str(arg.min_varargs) if arg.min_varargs > 0 else '0',
238 'max': str(arg.max_varargs) if arg.max_varargs > 0 else 'infinity',
239 })
240 if isinstance(arg, (Kwarg, PosArg)):
241 data.update({'default': arg.default or None})
242 if isinstance(arg, Kwarg):
243 data.update({'required': arg.required})
244 return data
245
246 mname = f'\\{func.name}' if func.name == '[index]' else func.name
247
248 data: FunctionDictType = {
249 'name': f'{func.obj.name}.{mname}' if isinstance(func, Method) else func.name,
250 'base_level': '##' if isinstance(func, Method) else '#',
251 'type_name_upper': 'Method' if isinstance(func, Method) else 'Function',
252 'type_name': 'method' if isinstance(func, Method) else 'function',
253 'description': func.description,
254 'notes': func.notes,
255 'warnings': func.warnings,
256 'example': func.example or None,
257 'signature_level': 'h4' if isinstance(func, Method) else 'h3',
258 'signature': render_signature(),
259 'has_args': bool(func.posargs or func.optargs or func.kwargs or func.varargs),
260 # Merge posargs and optargs by generating the *[optional]* tag for optargs
261 'posargs': {
262 'args': [gen_arg_data(x) for x in func.posargs] + [gen_arg_data(x, optional=True) for x in func.optargs]
263 } if func.posargs or func.optargs else None,
264 'kwargs': {'args': [gen_arg_data(x) for x in self.sorted_and_filtered(list(func.kwargs.values()))]} if func.kwargs else None,
265 'varargs': gen_arg_data(func.varargs) if func.varargs else None,
266 'arg_flattening': func.arg_flattening,
267
268 # For the feature taggs template
269 'since': func.since or None,
270 'deprecated': func.deprecated or None,
271 'optional': False,
272 'default': None
273 }
274
275 return data
276
277 def _write_object(self, obj: Object) -> None:
278 data = {
279 'name': obj.name,
280 'title': obj.long_name if obj.obj_type == ObjectType.RETURNED else obj.name,
281 'description': obj.description,
282 'notes': obj.notes,
283 'warnings': obj.warnings,
284 'long_name': obj.long_name,
285 'obj_type_name': _OBJ_ID_MAP[obj.obj_type].capitalize(),
286 'example': obj.example or None,
287 'has_methods': bool(obj.methods),
288 'has_inherited_methods': bool(obj.inherited_methods),
289 'has_subclasses': bool(obj.extended_by),
290 'is_returned': bool(obj.returned_by),
291 'extends': obj.extends_obj.name if obj.extends_obj else None,
292 'returned_by': [self._link_to_object(x) for x in self.sorted_and_filtered(obj.returned_by)],
293 'extended_by': [self._link_to_object(x) for x in self.sorted_and_filtered(obj.extended_by)],
294 'methods': [self._gen_func_or_method(m) for m in self.sorted_and_filtered(obj.methods)],
295 'inherited_methods': [self._gen_func_or_method(m) for m in self.sorted_and_filtered(obj.inherited_methods)],
296 }
297
298 self._write_template(data, self._gen_object_file_id(obj), 'object')
299
300 def _write_functions(self) -> None:
301 data = {'functions': [self._gen_func_or_method(x) for x in self.functions]}
302 self._write_template(data, 'root.functions')
303
304 def _root_refman_docs(self) -> None:
305 def gen_obj_links(objs: T.List[Object]) -> T.List[T.Dict[str, str]]:
306 ret: T.List[T.Dict[str, str]] = []
307 for o in objs:
308 ret += [{'indent': '', 'link': self._link_to_object(o), 'brief': self.brief(o)}]
309 for m in self.sorted_and_filtered(o.methods):
310 ret += [{'indent': ' ', 'link': self._link_to_object(m), 'brief': self.brief(m)}]
311 if o.obj_type == ObjectType.MODULE and self.extract_returned_by_module(o):
312 tmp = gen_obj_links(self.extract_returned_by_module(o))
313 tmp = [{**x, 'indent': ' ' + x['indent']} for x in tmp]
314 ret += [{'indent': ' ', 'link': '**New objects:**', 'brief': ''}]
315 ret += [*tmp]
316 return ret
317
318 data = {
319 'root': self._gen_filename('root'),
320 'elementary': gen_obj_links(self.elementary),
321 'returned': gen_obj_links(self.returned),
322 'builtins': gen_obj_links(self.builtins),
323 'modules': gen_obj_links(self.modules),
324 'functions': [{'indent': '', 'link': self._link_to_object(x), 'brief': self.brief(x)} for x in self.functions],
325 'enable_modules': self.enable_modules,
326 }
327
328 dummy = {'root': self._gen_filename('root')}
329
330 self._write_template(data, 'root')
331 self._write_template({**dummy, 'name': 'Elementary types'}, f'root.{_OBJ_ID_MAP[ObjectType.ELEMENTARY]}', 'dummy')
332 self._write_template({**dummy, 'name': 'Builtin objects'}, f'root.{_OBJ_ID_MAP[ObjectType.BUILTIN]}', 'dummy')
333 self._write_template({**dummy, 'name': 'Returned objects'}, f'root.{_OBJ_ID_MAP[ObjectType.RETURNED]}', 'dummy')
334
335 if self.enable_modules:
336 self._write_template({**dummy, 'name': 'Modules'}, f'root.{_OBJ_ID_MAP[ObjectType.MODULE]}', 'dummy')
337
338
339 def generate(self) -> None:
340 mlog.log('Generating markdown files...')
341 with mlog.nested():
342 self._write_functions()
343 for obj in self.objects:
344 if not self.enable_modules and (obj.obj_type == ObjectType.MODULE or obj.defined_by_module is not None):
345 continue
346 self._write_object(obj)
347 self._root_refman_docs()
348 self._configure_sitemap()
349 self._generate_link_def()
350
351 def _configure_sitemap(self) -> None:
352 '''
353 Replaces the `@REFMAN_PLACEHOLDER@` placeholder with the reference
354 manual sitemap. The structure of the sitemap is derived from the
355 file IDs.
356 '''
357 raw = self.sitemap_in.read_text(encoding='utf-8')
358 out = ''
359 for l in raw.split('\n'):
360 if '@REFMAN_PLACEHOLDER@' not in l:
361 out += f'{l}\n'
362 continue
363 mlog.log('Generating', mlog.bold(self.sitemap_out.as_posix()))
364 base_indent = l.replace('@REFMAN_PLACEHOLDER@', '')
365 for k in sorted(self.generated_files.keys()):
366 indent = base_indent + '\t' * k.count('.')
367 out += f'{indent}{self.generated_files[k]}\n'
368 self.sitemap_out.write_text(out, encoding='utf-8')
369
370 def _generate_link_def(self) -> None:
371 '''
372 Generate the link definition file for the refman_links hotdoc
373 plugin. The plugin is then responsible for replacing the [[tag]]
374 tags with custom HTML elements.
375 '''
376 data: T.Dict[str, str] = {}
377
378 # Objects and methods
379 for obj in self.objects:
380 obj_file = self._gen_filename(self._gen_object_file_id(obj), extension='html')
381 data[f'@{obj.name}'] = obj_file
382 for m in obj.methods:
383 data[f'{obj.name}.{m.name}'] = f'{obj_file}#{obj.name}{m.name}'
384
385 # Functions
386 funcs_file = self._gen_filename('root.functions', extension='html')
387 for fn in self.functions:
388 data[fn.name] = f'{funcs_file}#{fn.name}'
389
390 self.link_def_out.write_text(json.dumps(data, indent=2), encoding='utf-8')