gen_readme.py

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0

"""
A script to generate the README.md by either listing or embedding
the markdown files in the directory.
"""
from pathlib import Path
import sys


def canonicalize_name(name):
    # If the name format is "idx_name", then follow the index order.
    if name.find("_") != -1:
        order, rest = name[0 : name.find("_")], name[name.find("_") + 1 :]
        try:
            order = int(order)
            name = rest
        except ValueError:
            order = float("inf")
    else:
        order = float("inf")

    name = " ".join(
        [
            token[0].upper() + token[1:]
            for token in name.replace(".md", "").replace("-", " ").replace("_", " ").split(" ")
        ]
    )
    return order, name


def write_contents(filep, contents, level=0):
    """A helper function to write recursive contents to the file."""
    for (_, name), val in sorted(contents.items(), key=lambda c: c[0]):
        filep.write(" " * (level * 4))

        if isinstance(val, dict):
            # Directory.
            filep.write(f"- {name}\n")
            write_contents(filep, val, level + 1)
        else:
            # File.
            filep.write(f"- [{name}]({val})\n")
    return


def main(root_path):
    readme_file_path = root_path / "README.md"
    with open(readme_file_path, "w") as readme_file:
        # Header.
        readme_file.write(
            "<!--- Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -->\n"
            "<!--- SPDX-License-Identifier: Apache-2.0  -->\n"
            "<!--- Auto generated by docs/wiki/gen_readme.py. Do not touch. -->\n"
        )

        # Embed the content for the top-level files.
        contents = []
        for md_file_path in root_path.glob("*.md"):
            if md_file_path.name == "README.md":
                continue
            assert md_file_path.parent == root_path
            order, title = canonicalize_name(md_file_path.name)

            content = [f"## {title}\n"]
            with open(md_file_path, "r") as md_file:
                # Write the content but ignore comments (e.g., license header).
                for line in md_file:
                    if line.startswith("<!---"):
                        continue
                    content.append(line)
            content.append("\n\n")

            contents.append((order, content))

        for _, content in sorted(contents, key=lambda k: k[0]):
            for line in content:
                readme_file.write(line)

        # List file name of nested-level files.
        contents = {}
        for md_file_path in root_path.rglob("*.md"):
            if md_file_path.parent == root_path:
                # Skip the top-level.
                continue

            # Traverse path to root.
            curr_path = md_file_path.parent
            dirs = []
            while curr_path != root_path:
                dirs.append(curr_path.name)
                curr_path = curr_path.parent
            dirs.reverse()

            # Insert the file name to the proper position.
            curr_dir = contents
            for name in dirs:
                order, name = canonicalize_name(name)
                if (order, name) not in curr_dir:
                    curr_dir[(order, name)] = {}
                curr_dir = curr_dir[(order, name)]

            order, name = canonicalize_name(md_file_path.name)
            curr_dir[(order, name)] = md_file_path.relative_to(root_path)

        readme_file.write("\n\n## Table of Contents\n")
        write_contents(readme_file, contents)


if __name__ == "__main__":
    if len(sys.argv) < 1:
        print("Usage: gen_readme.py <wiki path>")
    main(Path(sys.argv[1]))