Generate Contents¶

# Generate the content for docs/glossary folder based on the format below:
#
# # <folder Name>
# - [<title>](<../../../file-path>)
#
# <folder-name>: the direct child folder name under docs/glossary.
# <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


def generate_readme_for_folders(base_path):
    # Iterate through each direct child folder in the base path
    for folder_name in os.listdir(base_path):
        folder_path = os.path.join(base_path, folder_name)

        # Only process directories
        if os.path.isdir(folder_path):
            readme_path = os.path.join(folder_path, "README.md")

            # If README.md doesn't exist, create it
            if not os.path.exists(readme_path):
                print(f"Creating README.md in {folder_path}")

                # Gather Markdown files and sort by marker date (latest to oldest)
                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))

                # Sort files by marker date (latest to oldest)
                md_files.sort(key=lambda x: x[0], reverse=True)

                # Generate content for README.md
                content = f"# {folder_name}\n\n"
                content += f"<!-- generate.py marker: {datetime.now().strftime('%Y%m%d')} -->\n\n"
                content += f"contents file is generated by generate.py script.\n\n"

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

                # Write the README.md file
                with open(readme_path, "w", encoding="utf-8") as readme_file:
                    readme_file.write(content)


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

# Replace 'your_base_directory' with the actual path to your base folder
base_directory = "docs/glossary"
generate_readme_for_folders(base_directory)