Combine all the source files (recursively) of a particular type into a single markdown document

combine_src.md

#!/usr/bin/env python3
"""
Source Code to Markdown Converter

This script creates a markdown file from source code files in a specified
folder. It recursively searches for files with a given extension and formats
them into a single markdown document with appropriate headings and code fences.

Usage:
    python script_name.py <folder_path> <file_extension>

Arguments:
    folder_path: The path to the folder containing source files (e.g., ~/src)
    file_extension: The extension of files to include (e.g., py or .py)

Output:
    A markdown file named '<folder_name>_<extension>.md' in the current
    directory.

Example:
    python script_name.py ~/src py

This will create a file named 'src_py.md' containing all Python source code from
the ~/src directory and its subdirectories, properly formatted in markdown.
"""

import argparse
import os


def create_markdown(folder, extension) -> None:
    # Normalize folder path and extension
    folder = os.path.expanduser(folder)
    extension = extension.lstrip(".")

    # Create output filename
    output_filename = f"{os.path.basename(folder)}_{extension}.md"

    with open(output_filename, "w", encoding="utf-8") as outfile:
        # Write the level one heading
        outfile.write(f"# {extension} source for {os.path.basename(folder)}\n\n")

        # Walk through the directory
        for root, _, files in os.walk(folder):
            for file in files:
                if file.endswith(f".{extension}"):
                    # Calculate the relative path
                    rel_path = os.path.relpath(
                        os.path.join(root, file),
                        folder,
                    )
                    # Calculate the heading level (number of path separators + 2)
                    level = rel_path.count(os.path.sep) + 2

                    # Write the file heading
                    outfile.write(f"{'#' * level} {rel_path}\n\n")

                    # Write the code fence start
                    outfile.write(f"```{extension}\n")

                    # Read and write the file contents
                    with open(
                        os.path.join(root, file), "r", encoding="utf-8"
                    ) as infile:
                        outfile.write(infile.read())

                    # Write the code fence end
                    outfile.write("\n```\n\n")

    print(f"Markdown file '{output_filename}' has been created.")


def main() -> None:
    """Parse command line arguments and call create_markdown."""
    parser = argparse.ArgumentParser(
        description="Create a markdown file from source files in a folder."
    )
    parser.add_argument("folder", help="The folder to search for source files")
    parser.add_argument(
        "extension",
        help="The file extension to look for (with or without leading dot)",
    )

    args = parser.parse_args()

    create_markdown(args.folder, args.extension)


if __name__ == "__main__":
    main()