Function generate_section_page

scripts/generate_docs_index.py:242–307

Generate or update a docs/zh/ index page for a section.

(
    section_key: str,
    docs_page_path: str,
    section_title: str,
    entries: List[dict],
    repo_root: Path,
    dry_run: bool = False,
)

def generate_section_page(
    section_key: str,
    docs_page_path: str,
    section_title: str,
    entries: List[dict],
    repo_root: Path,
    dry_run: bool = False,
) -> None:
    """Generate or update a docs/zh/ index page for a section."""
    docs_page = repo_root / docs_page_path
    docs_page.parent.mkdir(parents=True, exist_ok=True)

    # Read existing page to preserve any manually written intro
    existing_content = ""
    auto_marker = "<!-- AUTO-GENERATED: do not edit below this line -->"
    if docs_page.exists():
        existing_content = docs_page.read_text(encoding="utf-8")

    # Build front matter
    fm = {
        "title": section_title,
        "generated": datetime.now().strftime("%Y-%m-%d"),
        "doc_count": len(entries),
    }
    fm_str = "---\n"
    fm_str += f"title: {section_title}\n"
    fm_str += f"generated: '{fm['generated']}'\n"
    fm_str += f"doc_count: {fm['doc_count']}\n"
    fm_str += "---\n\n"

    # Build intro section (preserve existing if present, otherwise generate)
    if auto_marker in existing_content:
        intro = existing_content.split(auto_marker)[0]
    else:
        intro = fm_str + f"# {section_title}\n\n"

    # Build auto-generated table section
    auto_section = f"{auto_marker}\n\n"
    auto_section += f"> 共 **{len(entries)}** 篇文档，最后更新：{datetime.now().strftime('%Y-%m-%d')}\n\n"

    if section_key == "nmpa/guidance":
        # Group by device category
        groups = group_nmpa_guidance(entries)
        for group_name, group_entries in sorted(groups.items()):
            auto_section += f"## {group_name}\n\n"
            auto_section += "| 文档名称 | 文号 | 发布年份 |\n"
            auto_section += "|----------|------|----------|\n"
            for entry in sorted(group_entries, key=lambda e: e["effective_date"], reverse=True):
                auto_section += _entry_row(entry, repo_root) + "\n"
            auto_section += "\n"
    else:
        # Simple flat table
        auto_section += "| 文档名称 | 文号 | 发布年份 |\n"
        auto_section += "|----------|------|----------|\n"
        for entry in sorted(entries, key=lambda e: e["effective_date"], reverse=True):
            auto_section += _entry_row(entry, repo_root) + "\n"
        auto_section += "\n"