Emit Markdown files into docs_root/api/. Returns a dict of {section: [(name, rel_md_path), ...]} for nav building.
(parsed_files: list, docs_root: str)
| 456 | # ────────────────────────────────────────────────────────────────────────────── |
| 457 | |
| 458 | def emit_docs(parsed_files: list, docs_root: str) -> dict: |
| 459 | """ |
| 460 | Emit Markdown files into docs_root/api/. |
| 461 | Returns a dict of {section: [(name, rel_md_path), ...]} for nav building. |
| 462 | """ |
| 463 | api_root = os.path.join(docs_root, 'api') |
| 464 | os.makedirs(api_root, exist_ok=True) |
| 465 | |
| 466 | # Sections will be created on-demand per file (since sections mirror the source tree) |
| 467 | |
| 468 | # Collect all class/enum names for cross-linking |
| 469 | class_map = {} # name -> rel_md_path (assigned during iteration) |
| 470 | class_parent_map = {} # name -> parent_name |
| 471 | for pf in parsed_files: |
| 472 | rel_path = pf.get('relative_path', '') |
| 473 | section = _section_from_path(rel_path) |
| 474 | for c in pf.get('classes', []): |
| 475 | fname = c.get('name', '').lower() + '.md' |
| 476 | name = c.get('name', '') |
| 477 | class_map[name] = 'api/' + _safe_folder(section).replace(os.sep, '/') + '/' + fname |
| 478 | class_parent_map[name] = c.get('parent') |
| 479 | for e in pf.get('enums', []): |
| 480 | fname = e.get('name', '').lower() + '.md' |
| 481 | class_map[e.get('name', '')] = 'api/' + _safe_folder(section).replace(os.sep, '/') + '/' + fname |
| 482 | |
| 483 | nav = defaultdict(list) # section → [(display_name, rel_path_from_docs)] |
| 484 | all_entries = [] # for index page |
| 485 | |
| 486 | for pf in parsed_files: |
| 487 | rel_path = pf.get('relative_path', '') |
| 488 | |
| 489 | for cls in pf.get('classes', []): |
| 490 | name = cls.get('name', '') |
| 491 | if not name: |
| 492 | continue |
| 493 | section = _section_from_path(rel_path) |
| 494 | folder = os.path.join(api_root, _safe_folder(section)) |
| 495 | os.makedirs(folder, exist_ok=True) |
| 496 | md = _render_class(cls, class_map) |
| 497 | fname = name.lower() + '.md' |
| 498 | out_path = os.path.join(folder, fname) |
| 499 | with open(out_path, 'w', encoding='utf-8') as f: |
| 500 | f.write(md) |
| 501 | rel_md = 'api/' + _safe_folder(section).replace(os.sep, '/') + '/' + fname |
| 502 | nav[section].append((name, rel_md)) |
| 503 | all_entries.append({ |
| 504 | 'name': name, 'kind': cls.get('kind', 'class'), |
| 505 | 'brief': cls.get('brief', ''), 'path': rel_md, 'section': section, |
| 506 | 'parent': cls.get('parent') |
| 507 | }) |
| 508 | |
| 509 | for enm in pf.get('enums', []): |
| 510 | name = enm.get('name', '') |
| 511 | if not name: |
| 512 | continue |
| 513 | section = _section_from_path(rel_path) |
| 514 | folder = os.path.join(api_root, _safe_folder(section)) |
| 515 | os.makedirs(folder, exist_ok=True) |
no test coverage detected