Build_catalog

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/mermaid/gallery/build/build_catalog.py
Description	Not specified

Source Content

#!/usr/bin/env python3
"""Generate service-team-diagrams.md from diagrams.py.

Reference-mode doc (Diataxis): flat, factual, no stories. Code blocks are
emitted verbatim from the same source that fed the rendered gallery, so the
catalog and the gallery can never drift.
"""

from pathlib import Path
from diagrams import GROUPS, DIAGRAMS

OUT = Path("/Users/davidholmes/.copilot/skills/technical-writing/references/mermaid/service-team-diagrams.md")

GROUP_TITLES = {gid: title for gid, title, _ in GROUPS}


def selection_table() -> str:
    head = (
        "| To answer this question | Reach for | Type | Inline icons |\n"
        "|---|---|---|---|\n"
    )
    rows = []
    for d in DIAGRAMS:
        icons = "Yes" if d["icons"] else "No"
        rows.append(f"| {d['reader_q']} | {d['title']} | `{d['keyword']}` | {icons} |")
    return head + "\n".join(rows)


def diagram_section(d: dict) -> str:
    if d["icons"]:
        support = (
            f"Renders as `{d['keyword']}` in InteractiveMermaid. Carries inline "
            f"FontAwesome icons — give every actor, system, and outcome one."
        )
    else:
        support = (
            f"Renders as `{d['keyword']}` in InteractiveMermaid. Notation-only — "
            f"this type does not paint inline icons, so keep every label plain."
        )
    when = "\n".join(f"- {x}" for x in d["when"])
    avoid = "\n".join(f"- {x}" for x in d["avoid"])
    return f"""### {d['title']}

*{d['reader_q']}*

{support}

**Reach for it when**

{when}

**Not the right tool when**

{avoid}

```mermaid
{d['code']}
```

*What to notice: {d['notice']}*
"""


def build() -> str:
    parts = []
    parts.append("# Diagrams for digital service teams\n")
    parts.append(
        "Sixteen Mermaid diagram types, each matched to the one question it answers. "
        "Use it to pick the right picture for a service problem — discovery research, "
        "a service flow, an architecture, a delivery plan, or a live metric. Every "
        "example draws the same service, a parking permit, so the types are easy to "
        "compare side by side.\n"
    )
    parts.append(
        "Every diagram follows the house style — monotone-first, with semantic colour "
        "only where it teaches, and an inline FontAwesome icon on every node in the "
        "types that render them (flowchart, state, class, mindmap, block, ER labels). "
        "The icon vocabulary and the full render matrix live in "
        "[icons-and-surfaces.md](icons-and-surfaces.md).\n"
    )
    parts.append(
        "To see them rendered and agree on the house look, open the gallery at "
        "[gallery/index.html](../gallery/index.html) — point at a card and say "
        "\"that is the look we want.\" That shared reference is what keeps diagrams "
        "consistent whether a person or the model draws the next one.\n"
    )

    parts.append("## How to choose\n")
    parts.append(
        "The catalog follows the delivery lifecycle: understand users, design the "
        "service, show how it connects, plan and deliver, then run and measure. Find "
        "the phase, then the question closest to yours.\n"
    )
    parts.append(selection_table() + "\n")
    parts.append(
        "All sixteen types render in InteractiveMermaid (vanilla Mermaid 11). The "
        "`Inline icons` column marks which types paint inline FontAwesome icons on "
        "their labels — give every node one in those; keep labels plain in the rest. "
        "See [icons-and-surfaces.md](icons-and-surfaces.md).\n"
    )

    for gid, gtitle, gnote in GROUPS:
        parts.append(f"## {gtitle}\n")
        parts.append(gnote + "\n")
        for d in DIAGRAMS:
            if d["group"] == gid:
                parts.append(diagram_section(d))

    parts.append(
        "## Keep every diagram lint-clean\n\n"
        "Every block above passes the skill's linter. Before shipping a new diagram, "
        "run it:\n\n"
        "```bash\n"
        "python3 ~/.copilot/skills/technical-writing/scripts/mermaid_lint.py /path/to/file.md\n"
        "```\n\n"
        "The flowchart in this catalog still obeys the flowchart rules in "
        "[diagram-principles.md](diagram-principles.md): grouped by people versus "
        "automation, seven nodes or fewer, top-down, and colored only on the two "
        "outcome nodes. The other types are reference-only shapes — a journey is one "
        "straight track, an ER diagram holds no flow — so those flowchart rules do not "
        "apply to them.\n"
    )

    return "\n".join(parts)


OUT.write_text(build(), encoding="utf-8")
print(f"wrote {OUT}")
print(f"{len(DIAGRAMS)} diagram sections, {sum(1 for d in DIAGRAMS if d['icons'])} with inline icons")