generate_label_docs.py

#!/usr/bin/env python3
"""Generate markdown documentation from a labels JSON definition file.

Usage:
    python generate_label_docs.py
    python generate_label_docs.py --output LABELS.md
    python generate_label_docs.py --file my-labels.json
"""

import argparse
import json
import os
import sys
from urllib.parse import quote


DEFAULT_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "labels.json")


def load_labels(path):
    with open(path, encoding="utf-8") as f:
        return json.load(f)


def badge_url(label_text, color):
    """Generate a shields.io badge URL for a label."""
    # Shields.io uses '-' as segment separator and '_' as space.
    # Escape literal hyphens as '--' and underscores as '__' before URL-encoding.
    escaped = label_text.replace("-", "--").replace("_", "__")
    encoded = quote(escaped, safe="")
    c = color.lstrip("#")
    return f"https://img.shields.io/badge/{encoded}-{c}?style=flat&color={c}"


def badge_md(label_text, color, alt=None):
    """Generate a markdown image tag for a shields.io badge."""
    if alt is None:
        alt = label_text.replace(":", "").replace("/", "").strip()
    url = badge_url(label_text, color)
    return f"![{alt}]({url})"


def group_badge_url(group_name, color):
    """Generate a shields.io badge URL for a group overview row."""
    name_lower = group_name.lower().split()[0]
    c = color.lstrip("#")
    return f"https://img.shields.io/badge/{quote(name_lower, safe='')}-blue?color=%23{c}&labelColor={c}"


def group_badge_md(group_name, color):
    name_lower = group_name.lower().split()[0]
    c = color.lstrip("#")
    url = group_badge_url(group_name, color)
    return f"![{name_lower}]({url})"


def group_labels(labels):
    """Group a list of labels by their 'group' field, preserving order."""
    groups = {}
    order = []
    for label in labels:
        g = label.get("group", "Other")
        if g not in groups:
            groups[g] = []
            order.append(g)
        groups[g].append(label)
    return [(g, groups[g]) for g in order]


def generate_markdown(data):
    lines = []

    # Title
    lines.append("# 3DCityDB Tagging system")
    lines.append("")

    # Overview table
    lines.append("## Overview")
    lines.append("")
    lines.append("| Group | Base Color | Description | Example |")
    lines.append("| :--- | :--- | :--- | :--- |")

    groups = {g["name"]: g for g in data["groups"]}
    for group in data["groups"]:
        name = group["name"]
        color = group["base_color"]
        desc = group["description"]
        badge = group_badge_md(name, color)
        lines.append(f"| **{name}** | `{color}` | {desc} | {badge} |")

    lines.append("")

    # List of all tags (summary table)
    all_labels = list(data["shared_labels"])
    # Collect all repo-specific labels (deduplicated by name for the summary)
    seen = {l["name"].lower() for l in all_labels}
    for repo_labels in data.get("repo_labels", {}).values():
        for label in repo_labels:
            if label["name"].lower() not in seen:
                all_labels.append(label)
                seen.add(label["name"].lower())

    lines.append("## List of all tags")
    lines.append("")
    lines.append("| Label | Group | Description | Preview |")
    lines.append("| :--- | :--- | :--- | :--- |")

    for label in all_labels:
        name = label["name"]
        group = label.get("group", "")
        # Use a short description for the summary table
        desc = label.get("description", "")
        # Truncate long descriptions for the summary
        if len(desc) > 60:
            desc = desc[:57].rsplit(" ", 1)[0] + "..."
        badge = badge_md(name, label["color"])
        lines.append(f"| `{name}` | {group} | {desc} | {badge} |")

    lines.append("")
    lines.append("---")
    lines.append("")

    # Shared Tags section
    lines.append("## Shared Tags (All Repositories)")
    lines.append("")
    lines.append("The following tags should be applied consistently across all "
                 "3DCityDB repositories with the same colors.")
    lines.append("")

    grouped = group_labels(data["shared_labels"])
    group_heading_map = {
        "Type": "Type Tags",
        "Status": "Status Tags",
        "Priority": "Priority Tags",
        "Contribution": "Contribution Tags",
        "Release": "Release Tags",
        "Infrastructure and others": "Infrastructure and others tags",
    }

    for group_name, labels in grouped:
        heading = group_heading_map.get(group_name, f"{group_name} Tags")
        lines.append(f"### {heading}")
        lines.append("")
        lines.append("| Label | Color | Description | Preview |")
        lines.append("| :--- | :--- | :--- | :--- |")

        for label in labels:
            name = label["name"]
            color = label["color"].lstrip("#")
            desc = label.get("description", "")
            badge = badge_md(name, color)
            lines.append(f"| `{name}` | `#{color}` | {desc} | {badge} |")

        lines.append("")

    lines.append("---")
    lines.append("")

    # Domain-specific tags per repo
    lines.append("## Domain specific tags")
    lines.append("")
    lines.append("These tags are unique for a repo based on the repo content.")
    lines.append("")

    repo_display = {
        "3dcitydb/3dcitydb": "3dcitydb",
        "3dcitydb/citydb-tool": "citydb-tool",
        "3dcitydb/3dcitydb-mkdocs": "3dcitydb-mkdocs",
    }

    for repo in data["repositories"]:
        repo_labels = data.get("repo_labels", {}).get(repo, [])
        if not repo_labels:
            continue

        display_name = repo_display.get(repo, repo.split("/")[-1])
        lines.append(f"### Domain specific tags: {display_name}")
        lines.append("")
        lines.append(f"**Repository:** [github.com/{repo}](https://github.com/{repo})")
        lines.append("")
        lines.append("| Label | Color | Description | Preview |")
        lines.append("| :--- | :--- | :--- | :--- |")

        for label in repo_labels:
            name = label["name"]
            color = label["color"].lstrip("#")
            desc = label.get("description", "")
            badge = badge_md(name, color)
            lines.append(f"| `{name}` | `#{color}` | {desc} | {badge} |")

        lines.append("")
        lines.append("---")
        lines.append("")

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Generate markdown documentation from labels JSON."
    )
    parser.add_argument(
        "--file",
        default=DEFAULT_FILE,
        help=f"Path to labels JSON file (default: {DEFAULT_FILE})",
    )
    parser.add_argument(
        "--output", "-o",
        help="Output file path (default: stdout)",
    )
    args = parser.parse_args()

    data = load_labels(args.file)
    markdown = generate_markdown(data)

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(markdown)
        print(f"Documentation written to {args.output}", file=sys.stderr)
    else:
        print(markdown)


if __name__ == "__main__":
    main()