'
+ escaped
+ "{html.escape(title)}
" f"{html.escape(text)}
" ) def flow_panel(file_name: str, block_name: str) -> str: upstream, downstream = BLOCK_FLOWS.get(file_name, {}).get( block_name, ( "Earlier blocks or operator input feed this block.", "Later blocks in the same file or in the next analytical stage consume its output.", ), ) return ( "Flow arrows
" f"{html.escape(upstream)} → {html.escape(block_name)} → {html.escape(downstream)}
" ) def make_doc_for_file(file_name: str) -> str: path = ROOT / file_name source = path.read_text(encoding="utf-8") lines = source.splitlines() tree = ast.parse(source, filename=file_name) top_nodes = [node for node in tree.body if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))] blocks: list[tuple[str, str, str]] = [] if top_nodes: first_start = min( (item.lineno for item in getattr(top_nodes[0], "decorator_list", []) if hasattr(item, "lineno")), default=top_nodes[0].lineno, ) preamble_end = first_start - 1 if preamble_end >= 1: preamble_code = "\n".join(lines[:preamble_end]).rstrip() if preamble_code: blocks.append(("Module setup", "module", preamble_code)) for index, node in enumerate(top_nodes): next_node = top_nodes[index + 1] if index + 1 < len(top_nodes) else None start, end = block_span(node, next_node, len(lines)) code = "\n".join(lines[start - 1 : end]).rstrip() kind = "class" if isinstance(node, ast.ClassDef) else "function" blocks.append((node.name, kind, code)) page_lines = [ f"# {file_name}", "", f"Source file: [`{file_name}`](../{file_name})", "", FILE_INTROS[file_name], "", f"Main flow in one line: `{FILE_FLOW_STRIPS[file_name]}`", "", "How to read this page:", "", "- left side: the actual source code block", "- right side: a plain-English explanation for a beginner", "- read from top to bottom because later blocks depend on earlier ones", "", ] for title, kind, code in blocks: explanation = explain_block(file_name, "__module__" if kind == "module" else title, kind) page_lines.extend( [ f"## {title}", "", '| ', code_panel(code), " | ", '', explanation_panel("What this block is doing", explanation), flow_panel(file_name, title), explanation_panel( "How to think about it", "Treat this block as one small station in a pipeline. Ask: what comes in here, what gets changed here, and what comes out for the next block?", ), " | ", "