diff --git a/soleprint/atlas2/docgen/README.md b/soleprint/atlas2/docgen/README.md index f44859a..f5f2bcd 100644 --- a/soleprint/atlas2/docgen/README.md +++ b/soleprint/atlas2/docgen/README.md @@ -282,7 +282,7 @@ about either. ## Testing ```bash -make check # docgen's own suite: 348 after make sync, 333 with nothing +make check # docgen's own suite: 350 after make sync, 335 with nothing make check BOOK=out/book/x # one book's own level — or a project's .docgen/ make doctor # the machine; never fails ``` diff --git a/soleprint/atlas2/docgen/book/build.py b/soleprint/atlas2/docgen/book/build.py index 96a92e7..3ef8ab8 100644 --- a/soleprint/atlas2/docgen/book/build.py +++ b/soleprint/atlas2/docgen/book/build.py @@ -276,7 +276,8 @@ def clear(out) -> list[str]: def build_book(kind: str, source, out, *, slug: str | None = None, exclude=(), - ops: dict | None = None, suffixes=None, quiet: bool = False) -> Book: + ops: dict | None = None, suffixes=None, identity: str | None = None, + quiet: bool = False) -> Book: """One book's steps: larder, IR, view, pages, drawings. No minisite, no notebook. Those are a document's outputs and are assembled by `book/document.py`, which @@ -299,9 +300,9 @@ def build_book(kind: str, source, out, *, slug: str | None = None, exclude=(), if not quiet: print(text) - ir, larder = extract(kind, source, exclude=exclude, suffixes=suffixes) + ir, larder = extract(kind, source, exclude=exclude, suffixes=suffixes, identity=identity) if larder is None: - larder = Larder(kind=kind, identity=str(source), unit="document", seen=0) + larder = Larder(kind=kind, identity=identity or str(source), unit="document", seen=0) book = Book(slug=slug, larder=larder, out=out) book.ir = ir say(f" larder {larder.line()}") @@ -384,7 +385,7 @@ def build_book(kind: str, source, out, *, slug: str | None = None, exclude=(), def run(kind: str, source, out, *, slug: str | None = None, style: str = "lucid", theme: str | None = None, exclude=(), overlay=None, notes=None, - quiet: bool = False) -> Book: + identity: str | None = None, quiet: bool = False) -> Book: """One book, as a one-book document whose outputs live in its own directory. `book.json`, `steps/`, `minisite/` and `notebook.ipynb` land where they always did; @@ -398,7 +399,7 @@ def run(kind: str, source, out, *, slug: str | None = None, style: str = "lucid" name=slug, title=slug, build=out, inline=True, notes=Path(notes) if notes else None, parts=[Part(name=slug, kind=kind, source=Path(source), out=out, - exclude=tuple(exclude), overlay=overlay)], + exclude=tuple(exclude), overlay=overlay, identity=identity)], outputs=[Output("minisite", out / "minisite", style=style, theme=theme), Output("notebook", out / "notebook.ipynb", style=style, theme=theme)], ) diff --git a/soleprint/atlas2/docgen/book/config.py b/soleprint/atlas2/docgen/book/config.py index f7bb708..58b1e25 100644 --- a/soleprint/atlas2/docgen/book/config.py +++ b/soleprint/atlas2/docgen/book/config.py @@ -100,6 +100,10 @@ class Entry: overlay: Path | None = None exclude: tuple = () notes: Path | None = None + # The source as the run file wrote it. `source` is resolved so it can be + # read; this is what the ledger shows, because an absolute path is a fact + # about this machine and the outputs travel. + identity: str | None = None def line(self) -> str: return f"{self.name:<18} {self.kind:<8} {self.source} -> {self.out}" @@ -273,6 +277,7 @@ def _load_books(path: Path, data: dict) -> "RunFile": name=name, kind=kind, source=source, out=out, style=pick("style", "lucid"), theme=pick("theme"), overlay=overlay, exclude=tuple(exclude), notes=notes, + identity=str(raw[source_key]), )) seen_names, seen_outs = {}, {} @@ -343,7 +348,8 @@ def run(runfile, names=None, *, check: bool = False, quiet: bool = True): overlay = spec_mod.load(entry.overlay) book = build(entry.kind, entry.source, entry.out, slug=entry.name, style=entry.style, theme=entry.theme, exclude=entry.exclude, - overlay=overlay, notes=entry.notes, quiet=quiet) + overlay=overlay, notes=entry.notes, identity=entry.identity, + quiet=quiet) result["lost"] = [r["claim"] for r in book.compare() if not r["ok"]] except Exception as e: # noqa: BLE001 - one bad book must not cost the run result["error"] = f"{type(e).__name__}: {e}" @@ -512,7 +518,8 @@ def load_project(path: Path, data: dict) -> ProjectFile: f"({source}) — set [project] build outside it") parts.append(Part(name=book, kind=kind, source=source, out=out, exclude=tuple(exclude), overlay=overlay, - suffixes=tuple(ext) if ext else None)) + suffixes=tuple(ext) if ext else None, + identity=str(raw[src_key]))) # -- ops -------------------------------------------------------------------- ops = data.get("ops") or {} diff --git a/soleprint/atlas2/docgen/book/document.py b/soleprint/atlas2/docgen/book/document.py index dc2a18c..2f5a6d9 100644 --- a/soleprint/atlas2/docgen/book/document.py +++ b/soleprint/atlas2/docgen/book/document.py @@ -60,6 +60,7 @@ class Part: overlay: dict | None = None ops: dict = field(default_factory=dict) suffixes: tuple | None = None # code only: which extensions to read + identity: str | None = None # the source as written; the ledger shows this @dataclass @@ -318,7 +319,7 @@ def build(doc: Document, *, quiet: bool = True) -> Document: try: book = build_book(part.kind, part.source, part.out, slug=part.name, exclude=part.exclude, ops=part.ops, suffixes=part.suffixes, - quiet=quiet) + identity=part.identity, quiet=quiet) except Exception as e: # noqa: BLE001 - recorded, not raised reason = f"{type(e).__name__}: {str(e).splitlines()[0] if str(e) else ''}" doc.failed[part.name] = reason diff --git a/soleprint/atlas2/docgen/book/larder.py b/soleprint/atlas2/docgen/book/larder.py index e8ceff0..016f23b 100644 --- a/soleprint/atlas2/docgen/book/larder.py +++ b/soleprint/atlas2/docgen/book/larder.py @@ -40,7 +40,9 @@ discipline as `VISUAL_KEYS`: the architectural rule is a check, not a convention Paths are left as the caller gave them rather than resolved. An absolute path is not a secret but it is machine-specific, and `meta.root` is already a bare name -for exactly that reason. +for exactly that reason. A run file resolves its paths to read them, and still +hands the larder the path as the file wrote it: the outputs travel, and the +machine they were built on is nobody's business. """ import re diff --git a/soleprint/atlas2/docgen/docs/img/minimap.svg b/soleprint/atlas2/docgen/docs/img/minimap.svg index 99f7c64..8e14de8 100644 --- a/soleprint/atlas2/docgen/docs/img/minimap.svg +++ b/soleprint/atlas2/docgen/docs/img/minimap.svg @@ -1,7 +1,7 @@ - - -docgen.selftest — 2783 lines + + +docgen.selftest — 2806 lines own_py_files — function, 3 lines check — function, 5 lines _err — function, 7 lines @@ -17,10 +17,10 @@ problems — function, 6 lines _pages — function, 114 lines _documents — function, 161 lines -_projects — function, 64 lines +_projects — function, 87 lines load — function, 7 lines -_contract — function, 75 lines -named — function, 2 lines +_contract — function, 75 lines +named — function, 2 lines docgen.book — 316 lines Step — class, 20 lines to_dict — function, 10 lines @@ -68,383 +68,383 @@ docgen.emitters — 12 lines docgen.lab — 11 lines docgen.__main__ — 9 lines -docgen.ir — 7 lines -docgen.extractors — 2 lines -docgen.cli.emit — 257 lines -_parser — function, 7 lines -_size — function, 3 lines -auto — function, 16 lines -dot — function, 38 lines -erd — function, 11 lines -index — function, 14 lines -minimap — function, 14 lines -notebook — function, 41 lines -minisite — function, 31 lines -explore — function, 22 lines -main — function, 9 lines -docgen.cli.extract — 119 lines -_parser — function, 5 lines -_counts — function, 3 lines -python — function, 15 lines -code — function, 14 lines -db — function, 11 lines -openapi — function, 12 lines -usage — function, 15 lines -main — function, 7 lines -docgen.cli.run — 99 lines -main — function, 78 lines -docgen.cli.view — 90 lines -main — function, 75 lines -docgen.cli.scaffold — 88 lines -main — function, 66 lines -docgen.cli.common — 80 lines -Abort — class, 2 lines -read_json — function, 5 lines -read_ir — function, 11 lines -load_style — function, 7 lines -style_args — function, 3 lines -emit — function, 16 lines -dump_ir — function, 3 lines -docgen.cli.book — 77 lines -main — function, 55 lines -docgen.cli.check — 58 lines -main — function, 37 lines -docgen.cli.contract — 34 lines -main — function, 8 lines -docgen.cli.validate — 33 lines -main — function, 18 lines -docgen.emitters.notebook — 320 lines -_cell — function, 19 lines -_example — function, 26 lines -_params_cell — function, 18 lines -_call_cell — function, 40 lines -_call_md — function, 26 lines -_figure_md — function, 21 lines -_figure_attachments — function, 7 lines -build — function, 55 lines -emit — function, 3 lines -write — function, 5 lines -docgen.emitters.explore — 316 lines -_is_schema — function, 4 lines -_neighbourhood_svgs — function, 48 lines -render_one — function, 2 lines -render_one — function, 2 lines -_facts — function, 27 lines -emit — function, 172 lines -write — function, 17 lines -docgen.emitters.dot — 309 lines -RenderError — class, 2 lines -_esc — function, 2 lines -_attrs — function, 3 lines -_style_words — function, 9 lines -_node_attrs — function, 33 lines -emit — function, 113 lines -write — function, 31 lines -_within — function, 8 lines -_endpoints — function, 41 lines -walk — function, 4 lines -collapsed — function, 2 lines -first_leaf — function, 4 lines -_safe — function, 2 lines -_q — function, 2 lines -have_graphviz — function, 2 lines -render — function, 29 lines -docgen.emitters.minimap — 278 lines -_files — function, 57 lines -declared — function, 18 lines -build — function, 11 lines -_bands — function, 7 lines -_blocks — function, 19 lines -emit — function, 120 lines -marks_to_labels — function, 3 lines -docgen.emitters.erd — 276 lines -_truncate — function, 3 lines -_tables — function, 20 lines -_card_height — function, 3 lines -max_columns — function, 9 lines -layout — function, 25 lines -_field_y — function, 3 lines -emit — function, 146 lines -docgen.emitters.minisite — 270 lines -_note — function, 7 lines -_missing — function, 9 lines -_tree — function, 15 lines -walk — function, 7 lines -_page — function, 69 lines -write — function, 95 lines -put — function, 4 lines -docgen.emitters.index — 164 lines -_tree — function, 8 lines -_anchor — function, 5 lines -to_markdown — function, 84 lines -walk — function, 27 lines -to_sidebar — function, 26 lines -build — function, 13 lines -docgen.emitters.markdown — 146 lines -_url — function, 7 lines -_inline — function, 13 lines -keep — function, 3 lines -to_html — function, 91 lines -para — function, 3 lines -cells — function, 2 lines -docgen.emitters.paged — 119 lines -svg_width_px — function, 6 lines -_estimate_px — function, 10 lines -fits_for — function, 17 lines -fits — function, 6 lines -links_for — function, 15 lines -render — function, 19 lines -inline — function, 9 lines -docgen.emitters.auto — 64 lines -draw — function, 36 lines -docgen.book.config — 622 lines -ConfigError — class, 6 lines -__init__ — function, 3 lines -Entry — class, 15 lines -line — function, 2 lines -RunFile — class, 17 lines -select — function, 12 lines -_path — function, 6 lines -_within — function, 3 lines -_read — function, 9 lines -load — function, 18 lines -_load_books — function, 121 lines -pick — function, 3 lines -apply_reference — function, 11 lines -_checks — function, 13 lines -run — function, 36 lines -ProjectFile — class, 8 lines -books — function, 2 lines -load_project — function, 154 lines -select_parts — function, 9 lines -run_project — function, 41 lines -docgen.book.document — 449 lines -Output — class, 6 lines -Part — class, 11 lines -Document — class, 11 lines -apply_ops — function, 15 lines -clear_output — function, 27 lines -write_manifest — function, 3 lines -rendered_pages — function, 22 lines -caption — function, 14 lines -_note_step — function, 8 lines -_with_note — function, 11 lines -notebook_spec — function, 91 lines -build — function, 116 lines -say — function, 3 lines -_spots — function, 16 lines -known_spots — function, 3 lines -plan_spots — function, 9 lines -docgen.book.build — 420 lines -extract — function, 29 lines -spec_from — function, 71 lines -_load_cell — function, 46 lines -clear — function, 26 lines -build_book — function, 105 lines -say — function, 3 lines -run — function, 35 lines -docgen.book.checks — 378 lines -Loaded — class, 26 lines -__init__ — function, 15 lines -larder — function, 2 lines -measure — function, 2 lines -Report — class, 38 lines -__init__ — function, 3 lines -note — function, 2 lines -check — function, 8 lines -skip — function, 3 lines -total — function, 15 lines -generated — function, 89 lines -custom — function, 26 lines -_run_cells — function, 33 lines -_notes_drift — function, 7 lines -document — function, 72 lines -heading — function, 2 lines -document_failures — function, 9 lines -docgen.book.larder — 196 lines -_count — function, 13 lines -redact — function, 32 lines -Larder — class, 77 lines -__post_init__ — function, 7 lines -read — function, 3 lines -fail — function, 3 lines -to_dict — function, 13 lines -from_dict — function, 10 lines -line — function, 20 lines -of — function, 3 lines -docgen.book.notes — 162 lines -body — function, 6 lines -stub — function, 3 lines -Notes — class, 78 lines -__init__ — function, 3 lines -_read — function, 7 lines -document — function, 2 lines -book — function, 2 lines -path — function, 4 lines -drift — function, 27 lines -scaffold — function, 24 lines -images — function, 18 lines -data_uri — function, 2 lines -docgen.extractors.code — 282 lines -MissingParser — class, 2 lines -_parser — function, 21 lines -_name — function, 10 lines -_walk — function, 34 lines -extract_file — function, 27 lines -_count_errors — function, 5 lines -extract — function, 75 lines -docgen.extractors.usage — 269 lines -_template — function, 27 lines -_body — function, 10 lines -_shape — function, 15 lines -_graphql — function, 11 lines -extract — function, 133 lines -docgen.extractors.openapi — 191 lines -_modelgen — function, 28 lines -_type_name — function, 6 lines -_refs — function, 43 lines -extract — function, 76 lines -docgen.extractors.db — 161 lines -from_schema_dict — function, 82 lines -_relation — function, 10 lines -_plain_type — function, 6 lines -_dedupe — function, 9 lines -extract — function, 6 lines -docgen.extractors.python — 37 lines -extract — function, 14 lines -docgen.extractors.python.collect — 236 lines -Definition — class, 10 lines -Module — class, 12 lines -_Collector — class, 67 lines -__init__ — function, 3 lines -_define — function, 17 lines -visit_ClassDef — function, 5 lines -visit_FunctionDef — function, 5 lines -visit_Import — function, 8 lines -visit_ImportFrom — function, 14 lines -_first_line — function, 5 lines -_name_of — function, 15 lines -_resolve_relative — function, 16 lines -module_name — function, 26 lines -collect_file — function, 21 lines -collect — function, 13 lines -docgen.extractors.python.resolve — 184 lines -_id_for — function, 2 lines -_resolve — function, 32 lines -larder_of — function, 17 lines -to_ir — function, 98 lines -_point_at — function, 9 lines -docgen.ir.validate — 278 lines -IRError — class, 2 lines -_schema — function, 2 lines -_props — function, 5 lines -_fields — function, 4 lines -check — function, 108 lines -_check_larder — function, 58 lines -validate — function, 6 lines -check_model_matches_schema — function, 23 lines -docgen.ir.model — 165 lines -Meta — class, 38 lines -to_dict — function, 18 lines -Node — class, 21 lines -__post_init__ — function, 3 lines -to_dict — function, 8 lines -Edge — class, 15 lines -to_dict — function, 7 lines -Graph — class, 48 lines -node — function, 4 lines -edge — function, 4 lines -has — function, 2 lines -to_dict — function, 16 lines -from_dict — function, 6 lines -docgen.ops.filter — 485 lines -_rebuild — function, 57 lines -surviving_parent — function, 5 lines -lift — function, 6 lines -drop_kinds — function, 14 lines -only_kinds — function, 14 lines -drop_stdlib — function, 13 lines -drop_external — function, 3 lines -subtree — function, 13 lines -neighbourhood — function, 45 lines -collapse_to_depth — function, 18 lines -level — function, 6 lines -drop_builtins — function, 14 lines -overview — function, 35 lines -shape — function, 72 lines -rank_of — function, 9 lines -split — function, 24 lines -classify — function, 102 lines -docgen.ops.pages — 383 lines -slugify — function, 8 lines -_key — function, 8 lines -_under — function, 5 lines -_representative — function, 13 lines -page_ir — function, 67 lines -layout — function, 20 lines -paginate — function, 61 lines -unique — function, 6 lines -opens — function, 3 lines -visit — function, 30 lines -paginate_tables — function, 76 lines -coverage — function, 28 lines -for_view — function, 17 lines -docgen.style.extract — 222 lines -_values_from — function, 17 lines -_normalise — function, 45 lines -_svg_files — function, 25 lines -harvest — function, 43 lines -write — function, 7 lines -summarise — function, 13 lines -docgen.style.tokens — 211 lines -_top — function, 2 lines -_mode — function, 3 lines -_luminance — function, 6 lines -derive — function, 101 lines -accent — function, 2 lines -geometry — function, 14 lines -write — function, 7 lines -from_folder — function, 9 lines -docgen — 2 lines -docgen.emitters.minisite.onepage — 541 lines -_ledger — function, 54 lines -_slots — function, 15 lines -_fill — function, 4 lines -_sidebar — function, 17 lines -_sections — function, 15 lines -emit — function, 96 lines -write — function, 10 lines -docgen.lab.pg_probe — 150 lines -probe — function, 30 lines -_simplify — function, 3 lines -main — function, 25 lines -docgen.notebook.spec — 264 lines -_step — function, 4 lines -from_ir — function, 108 lines -_order — function, 5 lines -scaffold — function, 20 lines -merge — function, 58 lines -load — function, 2 lines -dump — function, 5 lines +docgen.ir — 7 lines +docgen.extractors — 2 lines +docgen.cli.emit — 257 lines +_parser — function, 7 lines +_size — function, 3 lines +auto — function, 16 lines +dot — function, 38 lines +erd — function, 11 lines +index — function, 14 lines +minimap — function, 14 lines +notebook — function, 41 lines +minisite — function, 31 lines +explore — function, 22 lines +main — function, 9 lines +docgen.cli.extract — 119 lines +_parser — function, 5 lines +_counts — function, 3 lines +python — function, 15 lines +code — function, 14 lines +db — function, 11 lines +openapi — function, 12 lines +usage — function, 15 lines +main — function, 7 lines +docgen.cli.run — 99 lines +main — function, 78 lines +docgen.cli.view — 90 lines +main — function, 75 lines +docgen.cli.scaffold — 88 lines +main — function, 66 lines +docgen.cli.common — 80 lines +Abort — class, 2 lines +read_json — function, 5 lines +read_ir — function, 11 lines +load_style — function, 7 lines +style_args — function, 3 lines +emit — function, 16 lines +dump_ir — function, 3 lines +docgen.cli.book — 77 lines +main — function, 55 lines +docgen.cli.check — 58 lines +main — function, 37 lines +docgen.cli.contract — 34 lines +main — function, 8 lines +docgen.cli.validate — 33 lines +main — function, 18 lines +docgen.emitters.notebook — 320 lines +_cell — function, 19 lines +_example — function, 26 lines +_params_cell — function, 18 lines +_call_cell — function, 40 lines +_call_md — function, 26 lines +_figure_md — function, 21 lines +_figure_attachments — function, 7 lines +build — function, 55 lines +emit — function, 3 lines +write — function, 5 lines +docgen.emitters.explore — 316 lines +_is_schema — function, 4 lines +_neighbourhood_svgs — function, 48 lines +render_one — function, 2 lines +render_one — function, 2 lines +_facts — function, 27 lines +emit — function, 172 lines +write — function, 17 lines +docgen.emitters.dot — 309 lines +RenderError — class, 2 lines +_esc — function, 2 lines +_attrs — function, 3 lines +_style_words — function, 9 lines +_node_attrs — function, 33 lines +emit — function, 113 lines +write — function, 31 lines +_within — function, 8 lines +_endpoints — function, 41 lines +walk — function, 4 lines +collapsed — function, 2 lines +first_leaf — function, 4 lines +_safe — function, 2 lines +_q — function, 2 lines +have_graphviz — function, 2 lines +render — function, 29 lines +docgen.emitters.minimap — 278 lines +_files — function, 57 lines +declared — function, 18 lines +build — function, 11 lines +_bands — function, 7 lines +_blocks — function, 19 lines +emit — function, 120 lines +marks_to_labels — function, 3 lines +docgen.emitters.erd — 276 lines +_truncate — function, 3 lines +_tables — function, 20 lines +_card_height — function, 3 lines +max_columns — function, 9 lines +layout — function, 25 lines +_field_y — function, 3 lines +emit — function, 146 lines +docgen.emitters.minisite — 270 lines +_note — function, 7 lines +_missing — function, 9 lines +_tree — function, 15 lines +walk — function, 7 lines +_page — function, 69 lines +write — function, 95 lines +put — function, 4 lines +docgen.emitters.index — 164 lines +_tree — function, 8 lines +_anchor — function, 5 lines +to_markdown — function, 84 lines +walk — function, 27 lines +to_sidebar — function, 26 lines +build — function, 13 lines +docgen.emitters.markdown — 146 lines +_url — function, 7 lines +_inline — function, 13 lines +keep — function, 3 lines +to_html — function, 91 lines +para — function, 3 lines +cells — function, 2 lines +docgen.emitters.paged — 119 lines +svg_width_px — function, 6 lines +_estimate_px — function, 10 lines +fits_for — function, 17 lines +fits — function, 6 lines +links_for — function, 15 lines +render — function, 19 lines +inline — function, 9 lines +docgen.emitters.auto — 64 lines +draw — function, 36 lines +docgen.book.config — 629 lines +ConfigError — class, 6 lines +__init__ — function, 3 lines +Entry — class, 19 lines +line — function, 2 lines +RunFile — class, 17 lines +select — function, 12 lines +_path — function, 6 lines +_within — function, 3 lines +_read — function, 9 lines +load — function, 18 lines +_load_books — function, 122 lines +pick — function, 3 lines +apply_reference — function, 11 lines +_checks — function, 13 lines +run — function, 37 lines +ProjectFile — class, 8 lines +books — function, 2 lines +load_project — function, 155 lines +select_parts — function, 9 lines +run_project — function, 41 lines +docgen.book.document — 450 lines +Output — class, 6 lines +Part — class, 12 lines +Document — class, 11 lines +apply_ops — function, 15 lines +clear_output — function, 27 lines +write_manifest — function, 3 lines +rendered_pages — function, 22 lines +caption — function, 14 lines +_note_step — function, 8 lines +_with_note — function, 11 lines +notebook_spec — function, 91 lines +build — function, 116 lines +say — function, 3 lines +_spots — function, 16 lines +known_spots — function, 3 lines +plan_spots — function, 9 lines +docgen.book.build — 421 lines +extract — function, 29 lines +spec_from — function, 71 lines +_load_cell — function, 46 lines +clear — function, 26 lines +build_book — function, 106 lines +say — function, 3 lines +run — function, 35 lines +docgen.book.checks — 378 lines +Loaded — class, 26 lines +__init__ — function, 15 lines +larder — function, 2 lines +measure — function, 2 lines +Report — class, 38 lines +__init__ — function, 3 lines +note — function, 2 lines +check — function, 8 lines +skip — function, 3 lines +total — function, 15 lines +generated — function, 89 lines +custom — function, 26 lines +_run_cells — function, 33 lines +_notes_drift — function, 7 lines +document — function, 72 lines +heading — function, 2 lines +document_failures — function, 9 lines +docgen.book.larder — 198 lines +_count — function, 13 lines +redact — function, 32 lines +Larder — class, 77 lines +__post_init__ — function, 7 lines +read — function, 3 lines +fail — function, 3 lines +to_dict — function, 13 lines +from_dict — function, 10 lines +line — function, 20 lines +of — function, 3 lines +docgen.book.notes — 162 lines +body — function, 6 lines +stub — function, 3 lines +Notes — class, 78 lines +__init__ — function, 3 lines +_read — function, 7 lines +document — function, 2 lines +book — function, 2 lines +path — function, 4 lines +drift — function, 27 lines +scaffold — function, 24 lines +images — function, 18 lines +data_uri — function, 2 lines +docgen.extractors.code — 282 lines +MissingParser — class, 2 lines +_parser — function, 21 lines +_name — function, 10 lines +_walk — function, 34 lines +extract_file — function, 27 lines +_count_errors — function, 5 lines +extract — function, 75 lines +docgen.extractors.usage — 269 lines +_template — function, 27 lines +_body — function, 10 lines +_shape — function, 15 lines +_graphql — function, 11 lines +extract — function, 133 lines +docgen.extractors.openapi — 191 lines +_modelgen — function, 28 lines +_type_name — function, 6 lines +_refs — function, 43 lines +extract — function, 76 lines +docgen.extractors.db — 161 lines +from_schema_dict — function, 82 lines +_relation — function, 10 lines +_plain_type — function, 6 lines +_dedupe — function, 9 lines +extract — function, 6 lines +docgen.extractors.python — 37 lines +extract — function, 14 lines +docgen.extractors.python.collect — 236 lines +Definition — class, 10 lines +Module — class, 12 lines +_Collector — class, 67 lines +__init__ — function, 3 lines +_define — function, 17 lines +visit_ClassDef — function, 5 lines +visit_FunctionDef — function, 5 lines +visit_Import — function, 8 lines +visit_ImportFrom — function, 14 lines +_first_line — function, 5 lines +_name_of — function, 15 lines +_resolve_relative — function, 16 lines +module_name — function, 26 lines +collect_file — function, 21 lines +collect — function, 13 lines +docgen.extractors.python.resolve — 184 lines +_id_for — function, 2 lines +_resolve — function, 32 lines +larder_of — function, 17 lines +to_ir — function, 98 lines +_point_at — function, 9 lines +docgen.ir.validate — 278 lines +IRError — class, 2 lines +_schema — function, 2 lines +_props — function, 5 lines +_fields — function, 4 lines +check — function, 108 lines +_check_larder — function, 58 lines +validate — function, 6 lines +check_model_matches_schema — function, 23 lines +docgen.ir.model — 165 lines +Meta — class, 38 lines +to_dict — function, 18 lines +Node — class, 21 lines +__post_init__ — function, 3 lines +to_dict — function, 8 lines +Edge — class, 15 lines +to_dict — function, 7 lines +Graph — class, 48 lines +node — function, 4 lines +edge — function, 4 lines +has — function, 2 lines +to_dict — function, 16 lines +from_dict — function, 6 lines +docgen.ops.filter — 485 lines +_rebuild — function, 57 lines +surviving_parent — function, 5 lines +lift — function, 6 lines +drop_kinds — function, 14 lines +only_kinds — function, 14 lines +drop_stdlib — function, 13 lines +drop_external — function, 3 lines +subtree — function, 13 lines +neighbourhood — function, 45 lines +collapse_to_depth — function, 18 lines +level — function, 6 lines +drop_builtins — function, 14 lines +overview — function, 35 lines +shape — function, 72 lines +rank_of — function, 9 lines +split — function, 24 lines +classify — function, 102 lines +docgen.ops.pages — 383 lines +slugify — function, 8 lines +_key — function, 8 lines +_under — function, 5 lines +_representative — function, 13 lines +page_ir — function, 67 lines +layout — function, 20 lines +paginate — function, 61 lines +unique — function, 6 lines +opens — function, 3 lines +visit — function, 30 lines +paginate_tables — function, 76 lines +coverage — function, 28 lines +for_view — function, 17 lines +docgen.style.extract — 222 lines +_values_from — function, 17 lines +_normalise — function, 45 lines +_svg_files — function, 25 lines +harvest — function, 43 lines +write — function, 7 lines +summarise — function, 13 lines +docgen.style.tokens — 211 lines +_top — function, 2 lines +_mode — function, 3 lines +_luminance — function, 6 lines +derive — function, 101 lines +accent — function, 2 lines +geometry — function, 14 lines +write — function, 7 lines +from_folder — function, 9 lines +docgen — 2 lines +docgen.emitters.minisite.onepage — 540 lines +_ledger — function, 54 lines +_slots — function, 15 lines +_fill — function, 4 lines +_sidebar — function, 17 lines +_sections — function, 15 lines +emit — function, 96 lines +write — function, 10 lines +docgen.lab.pg_probe — 150 lines +probe — function, 30 lines +_simplify — function, 3 lines +main — function, 25 lines +docgen.notebook.spec — 264 lines +_step — function, 4 lines +from_ir — function, 108 lines +_order — function, 5 lines +scaffold — function, 20 lines +merge — function, 58 lines +load — function, 2 lines +dump — function, 5 lines docgen -docgen -docgen.cli -docgen.cli -docgen.emitters -docgen.emitters -docgen.book -docgen.extractors -docgen.extractors -docgen.extractors.python -docgen.ir -docgen.ops -docgen.ops -docgen.style -(root) -docgen.emitters.minisite -docgen.lab -docgen.notebook -selftest +docgen +docgen.cli +docgen.cli +docgen.emitters +docgen.emitters +docgen.book +docgen.extractors +docgen.extractors +docgen.extractors.python +docgen.ir +docgen.ops +docgen.ops +docgen.style +(root) +docgen.emitters.minisite +docgen.lab +docgen.notebook +selftest book style reference @@ -454,58 +454,58 @@ emitters lab __main__ -ir -extractors -emit -extract -run -view -scaffold -common -book -check -contract -validate -notebook -explore -dot -minimap -erd -minisite -index -markdown -paged -auto -config -document -build -checks -larder -notes -code -usage -openapi -db -python -collect -resolve -validate -model -filter -pages -extract -tokens -docgen -onepage -pg_probe -spec - -module - -class - -interface - -function -55 files · 13,050 lines · 1px ≈ 2.0 lines +ir +extractors +emit +extract +run +view +scaffold +common +book +check +contract +validate +notebook +explore +dot +minimap +erd +minisite +index +markdown +paged +auto +config +document +build +checks +larder +notes +code +usage +openapi +db +python +collect +resolve +validate +model +filter +pages +extract +tokens +docgen +onepage +pg_probe +spec + +module + +class + +interface + +function +55 files · 13,083 lines · 1px ≈ 2.0 lines diff --git a/soleprint/atlas2/docgen/docs/index.html b/soleprint/atlas2/docgen/docs/index.html index 78b2969..57ebace 100644 --- a/soleprint/atlas2/docgen/docs/index.html +++ b/soleprint/atlas2/docgen/docs/index.html @@ -1129,10 +1129,10 @@ make doctor - - - - + + + +
contextchecksskipped
in the repo, synced348—
copied out, bare python3331tree-sitter, OpenAPI, the in-place case
copied out, synced340OpenAPI, the in-place case
copied out, synced, DOCGEN_REFERENCE set347
in the repo, synced350—
copied out, bare python3333tree-sitter, OpenAPI, the in-place case
copied out, synced342OpenAPI, the in-place case
copied out, synced, DOCGEN_REFERENCE set349 the in-place case — correctly, there is no repo above
@@ -1473,14 +1473,14 @@ make lock # after editing pyproject commandasks aboutfails? make doctorthe machine — what is installed never; it reports - make checkdocgen — 348 checks + make checkdocgen — 350 checks exit 1 make check BOOK=<dir>that one book, or a project's document exit 1

- All 348 after make sync, 333 with nothing optional installed — the + All 350 after make sync, 335 with nothing optional installed — the suite skips rather than fails when tree-sitter, lxml or the OpenAPI reader is absent. See standalone for the counts outside the repo. Among them, two that keep this page's structure true: nothing outside diff --git a/soleprint/atlas2/docgen/emitters/minisite/onepage.py b/soleprint/atlas2/docgen/emitters/minisite/onepage.py index aedcccc..64fea60 100644 --- a/soleprint/atlas2/docgen/emitters/minisite/onepage.py +++ b/soleprint/atlas2/docgen/emitters/minisite/onepage.py @@ -179,10 +179,10 @@ CSS = """/* Generated by docgen. The layout five demos converged on: a sticky si --muted: __MUTED__; --dim: __DIM__; --accent: __ACCENT__; - /* Used by the ledger's "incomplete" panel. Declared here because it was not, + /* What was lost: the ledger's "incomplete" panel. Declared here because it was not, and an undefined custom property falls back silently — the warning rendered in the ordinary text colour, which is the one place it must not. */ - --artery: __ARTERY__; + --lost: __LOST__; --ok: __OK__; } * { margin: 0; padding: 0; box-sizing: border-box; } @@ -247,8 +247,7 @@ body { text-transform: uppercase; letter-spacing: .04em; } .lede { color: var(--dim); font-size: 12px; margin-bottom: 1.5rem; } -/* The convention both spr/docs and sms/docs arrived at independently: - inline and scaled to the column, click for the full thing. */ +/* Inline and scaled to the column, click for the full thing. */ .figure { margin: 1rem 0 1.5rem; } .figure a { display: block; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; background: var(--surface); } @@ -267,11 +266,11 @@ body { .ledger dd { margin: 0; color: var(--text); font-size: 12.5px; } .ledger dd .sub { display: block; color: var(--muted); font-size: 11px; margin-top: .2rem; overflow-wrap: anywhere; } -.ledger .lost { color: var(--artery); } +.ledger .lost { color: var(--lost); } .ledger .kept { color: var(--ok); } -.gap { border: 1px solid var(--artery); border-left-width: 3px; border-radius: 6px; +.gap { border: 1px solid var(--lost); border-left-width: 3px; border-radius: 6px; background: var(--surface); padding: .7rem .9rem; margin: 0 0 1.5rem; font-size: 12px; } -.gap b { color: var(--artery); } +.gap b { color: var(--lost); } .gap ul { margin: .4rem 0 0 1.1rem; color: var(--muted); } .gap code { font-size: 11px; } @@ -305,7 +304,7 @@ body { .fig.actual svg { max-width: none; } .fig a:hover polygon, .fig a:hover path { stroke: var(--accent); } .caption { color: var(--dim); font-size: 11px; margin: .4rem 0 1.2rem; } -.caption.warn { color: var(--artery); } +.caption.warn { color: var(--lost); } .children { columns: 2; margin: .4rem 0 1.4rem; list-style: none; } .children li { margin-bottom: 2px; } .books { display: grid; gap: 1rem; margin: 1rem 0 2rem; } @@ -382,7 +381,7 @@ def _slots(style) -> dict: "__MUTED__": s("text-muted"), "__DIM__": s("text-dim"), "__ACCENT__": s("accent"), - "__ARTERY__": s("error") or s("artery"), + "__LOST__": s("error") or s("artery"), "__OK__": s("ok") or s("atlas"), "__FONT__": '"Segoe UI", Inter, system-ui, -apple-system, Arial, sans-serif', } diff --git a/soleprint/atlas2/docgen/selftest.py b/soleprint/atlas2/docgen/selftest.py index 86611ae..6e9e280 100644 --- a/soleprint/atlas2/docgen/selftest.py +++ b/soleprint/atlas2/docgen/selftest.py @@ -2651,6 +2651,29 @@ def _projects(): ) check("[ops] applies to every book", all(p.ops.get("drop_stdlib") for p in doc.parts)) check("an output's width is kept", next(o for o in doc.outputs if o.emitter == "minisite").width == 700) + + # The outputs are what travels: a minisite or a notebook handed to someone + # else says nothing about the machine that built it, and nothing of the + # toolkit behind it. Its own source's names are fair game — that is the + # content — so the source here holds none of the words scanned for. + doc_mod = __import__(f"{PKG}.book.document", fromlist=["*"]) + with _ctx.redirect_stdout(_io.StringIO()): + doc_mod.build(doc) + check("the ledger names a source the way the run file wrote it", + [b.larder.identity for b in doc.books] == ["src", "shop.json"], + [b.larder.identity for b in doc.books]) + leaks = [] + toolkit = re.compile(r"\b(soleprint|spr|artery|veins?|shunts?|plexus(es)?)\b", re.I) + for out_dir in (base / "out" / "minisite", base / "out" / "nb"): + for f in sorted(out_dir.rglob("*")): + if not f.is_file() or f.suffix not in (".html", ".css", ".js", ".svg", ".ipynb", ".json"): + continue + text = f.read_text() + if str(base) in text or str(Path.home()) in text: + leaks.append(f"{f.relative_to(base)}: an absolute path") + leaks += [f"{f.relative_to(base)}: {m.group(0)}" for m in toolkit.finditer(text)][:2] + check("no output carries an absolute path or the toolkit's own words", not leaks, leaks[:6]) + books_file, _ = load('[[book]]\nname = "a"\nroot = "src"\n', "books.toml") check("a [[book]] list still loads as it did", isinstance(books_file, cfg.RunFile))