icp_doc_builder.py

Go to the documentation of this file.

# Copyright (C) 2024 Ethan Uppal.
# SPDX-License-Identifier: MIT
 
import os
import re
import sys
 
 
def change_extension(filename, new_extension):
    name, _ = os.path.splitext(filename)
    return f"{name}.{new_extension}"
 
 
# yes this documentation was mostly generated by ChatGPT
# no I don't care, it's Python
class ICPDocumentationBuilder:
    """
    A class used to build documentation for an ICP implementation.
 
    ...
 
    Attributes
    ----------
    search_dir : str
        The directory to search for source files.
    out_dir : str
        The directory to write the output markdown files.
    main_file : str
        The main documentation file.
    all_sources : set
        A set of all sources found in the source files.
    registration_names : dict
        Associates each ICP type name with its registration name.
 
    Methods
    -------
    extract(file, contents):
        Extracts the documentation from the given file contents and writes it to a markdown file.
    build():
        Searches for source files in the search directory and extracts their documentation.
    """
 
    def __init__(self, search_dir, out_dir, main_file):
        """
        Constructs a new ICPDocumentationBuilder.
 
        Parameters
        ----------
        search_dir : str
            The directory to search for source files.
        out_dir : str
            The directory to write the output markdown files.
        main_file : str
            A path to the main markdown file.
        """
        self.search_dir = search_dir
        self.out_dir = out_dir
        self.main_file = main_file
        self.all_sources = set()
 
    def extract(self, file, contents):
        """
        Extracts the documentation from the given file contents and writes it to a markdown file.
 
        Parameters
        ----------
        file : str
            The name of the file to extract documentation from.
        contents : str
            The contents of the file.
        """
 
        pattern = r"/\*\s*(#step|#name|#desc)(.*?)\*/"
        comments = re.findall(pattern, contents, re.DOTALL)
        if not comments:
            return
        md_filename = "icp_" + change_extension(file, "md")
        made_description = False
        with open(self.out_dir + "/" + md_filename, "w") as md_file:
            step_cnt = 1
            for kind, comment in comments:
                comment_parts = comment.strip().split("Sources:", 1)
                comment_text = (
                    re.sub(r"\n *", "\n", comment_parts[0])
                    .replace("\n*", "\n")
                    .replace("\n *", "\n")
                )
                sources = (
                    re.findall(r"https?://[^\s]+", comment_parts[1])
                    if len(comment_parts) > 1
                    else []
                )
                self.all_sources.update(sources)
                if kind == "#name":
                    doxygen_ref = f"{comment_text.lower()}_icp".replace("-", "_")
                    md_file.write(f"\\page {doxygen_ref} {comment_text} ICP\n")
 
                    register_pattern = r"/\*\s*#register(.*?)\*/"
                    registers = re.findall(register_pattern, contents, re.DOTALL)
                    assert len(registers) == 1
                    register_name = registers[0].strip()
 
                    conf_pattern = r'/\*\s*#conf\s+"([^"]*)"\s+(.*?)\*/'
                    confs = re.findall(conf_pattern, contents, re.DOTALL)
 
                    if not confs:
                        md_file.write(
                            f'\\par Usage\nYou can construct a new instance of {comment_text} ICP with `icp::ICP::from_method("{register_name}")`.'
                        )
                    else:
                        md_file.write(
                            f'\\par Usage\nYou can construct a new instance of {comment_text} ICP with `icp::ICP::from_method("{register_name}", config)`. Supply the following parameters to `config` (via icp::ICP::Config::set):\n'
                        )
                        md_file.write("\nKey | Description\n--- | ---\n")
                        for key, descr in confs:
                            descr_lines = descr.split("\n")
                            cleaned_lines = [
                                line.strip().removeprefix("*") for line in descr_lines
                            ]
                            descr = " ".join(cleaned_lines)
                            md_file.write(f'`"{key}"` | {descr}\n')
                elif kind == "#step":
                    if not made_description:
                        md_file.write("\n\\par Description\n")
                        made_description = True
                    lines = comment_text.splitlines()
                    first_line_parts = lines[0].split(":", 1)
                    if len(first_line_parts) == 2:
                        lines[0] = f"**{first_line_parts[0]}**:{first_line_parts[1]}"
                    else:
                        lines[0] = f"**{first_line_parts[0]}**"
                    step_text = "\n".join("    " + line for line in lines)
                    md_file.write(f"\n{step_cnt}. {step_text}\n")
                    step_cnt += 1
                    if sources:
                        md_file.write("    Sources:  \n")
                        for source in sources:
                            md_file.write(f"    - {source}\n")
                        md_file.write("\n")
                elif kind == "#desc":
                    icp_description = comment_text
                    md_file.write(f"\n\\par Description\n{comment_text}\n")
                    made_description = True
            md_file.write(
                "\n\nRead \\ref icp_sources for a list of all resources used in this project."
            )
            md_file.write(
                f"\nThis page was automatically generated from {file} with {os.path.basename(__file__)}."
            )
        return doxygen_ref, icp_description
 
    def update_main(self, doxygen_refs):
        with open(self.main_file, "r") as file:
            content = file.read()
 
            start_marker = "<!-- ICP_DOCS_BUILDER EDIT MARKER START -->"
            end_marker = "<!-- ICP_DOCS_BUILDER EDIT MARKER END -->"
 
            start_index = content.find(start_marker)
            end_index = content.find(end_marker)
 
            if start_index != -1 and end_index != -1:
                new_content = (
                    content[: start_index + len(start_marker) + 1]
                    + "\n".join(
                        sorted(
                            [
                                f"- \\ref {doxygen_ref} ({icp_description})"
                                for (doxygen_ref, icp_description) in doxygen_refs
                            ]
                        )
                    )
                    + "\n"
                    + content[end_index:]
                )
 
                with open(self.main_file, "w") as file:
                    file.write(new_content)
 
    def build(self):
        """
        Searches for source files in the search directory and extracts their documentation.
        """
        doxygen_refs = []
        for root, _, files in os.walk(self.search_dir):
            for file in files:
                if file.endswith(".cpp"):
                    with open(os.path.join(root, file), "r") as f:
                        result = self.extract(file, f.read())
                        if result:
                            doxygen_ref, icp_description = result
                            doxygen_refs.append((doxygen_ref, icp_description))
        self.update_main(doxygen_refs)
        os.makedirs(self.out_dir + "/extra", exist_ok=True)
        with open(self.out_dir + "/extra/sources.md", "w") as md_file:
            md_file.write("\\page icp_sources ICP Sources\n\n")
            md_file.write(
                "This list contains all resources used in implementing ICP for this project in alphabetical order.\n\n"
            )
            for source in sorted(list(self.all_sources)):
                md_file.write(f" - {source}\n")
 
 
if __name__ == "__main__":
    if len(sys.argv) != 4:
        print(
            f"usage: python3 {os.path.basename(__file__)} search_dir out_dir main_file"
        )
        sys.exit(1)
 
    os.makedirs(sys.argv[2], exist_ok=True)
 
    doc_builder = ICPDocumentationBuilder(sys.argv[1], sys.argv[2], sys.argv[3])
    doc_builder.build()