Skip to content

Generate Contents

# Generate section indexes based on the format below:
#
# # <folder Name>
# - [<title>](<../../../scripts/file-path>)
#
# <folder-name>: the configured folder name or title.
# <title>: the title("# <title>") of markdown.
# <file-path>: the file name.
#
# the contents are sorted based on the second line marker
# <!-- generate.py marker: 20250123 -->


import os
import re
from datetime import datetime


INDEX_TARGETS = [
    {
        "path": "docs/glossary",
        "mode": "children",
    },
    {
        "path": "docs/engineer/ai-exploration",
        "mode": "folder",
        "title": "AI Exploration",
    },
]


def generate_readme_for_folder(folder_path, title=None):
    readme_path = os.path.join(folder_path, "README.md")

    if os.path.exists(readme_path):
        return

    print(f"Creating README.md in {folder_path}")

    md_files = []
    for file_name in os.listdir(folder_path):
        file_path = os.path.join(folder_path, file_name)
        if file_name.endswith(".md") and file_name != "README.md":
            marker_date = extract_marker_date(file_path)
            md_files.append((marker_date, file_name))

    # Newest first; filenames make ordering deterministic when dates match.
    md_files.sort(key=lambda item: (-item[0], item[1].casefold()))

    section_title = title or os.path.basename(folder_path)
    content = f"# {section_title}\n\n"
    content += f"<!-- generate.py marker: {datetime.now().strftime('%Y%m%d')} -->\n\n"
    content += "contents file is generated by generate.py script.\n\n"

    for _, file_name in md_files:
        file_path = os.path.join(folder_path, file_name)
        page_title = extract_title(file_path)
        content += f"- [{page_title}](../../../scripts/{file_name})\n"

    with open(readme_path, "w", encoding="utf-8") as readme_file:
        readme_file.write(content)


def generate_readme_for_folders(base_path):
    for folder_name in sorted(os.listdir(base_path)):
        folder_path = os.path.join(base_path, folder_name)
        if os.path.isdir(folder_path):
            generate_readme_for_folder(folder_path)


def extract_title(file_path):
    """Extract the first title (# ...) from a Markdown file."""
    try:
        with open(file_path, "r", encoding="utf-8") as file:
            for line in file:
                line = line.strip()
                if line.startswith("# "):  # Look for the first Markdown title
                    return line[2:].strip()  # Remove the '# ' and return the title
    except Exception as e:
        print(f"Error reading file {file_path}: {e}")
    return "Untitled"  # Default title if no title is found


def extract_marker_date(file_path):
    """Extract the marker date from the file (e.g., <!-- generate.py marker: YYYYMMDD -->)."""
    try:
        with open(file_path, "r", encoding="utf-8") as file:
            for line in file:
                line = line.strip()
                # Match the marker tag using regex
                match = re.search(r"<!-- generate\.py marker: (\d{8}) -->", line)
                if match:
                    return int(match.group(1))  # Return the date as an integer for sorting
    except Exception as e:
        print(f"Error reading file {file_path}: {e}")
    return 0  # Default to 0 if no marker is found

for target in INDEX_TARGETS:
    mode = target["mode"]
    if mode == "children":
        generate_readme_for_folders(target["path"])
    elif mode == "folder":
        generate_readme_for_folder(target["path"], title=target.get("title"))
    else:
        raise ValueError(f"Unknown index target mode: {mode}")

Comments