Improve documentation of Python files.

- Add `generate_changelog.py`.
- Improve typing and documentation.

Author: ZCG-coder

tools/add_copyright_header.py

@@ -20,6 +20,10 @@
 #  SOFTWARE.                                                                                        #
 #####################################################################################################
 
+"""
+Add a copyright header to all files.
+"""
+
 import datetime
 import re
 from pathlib import Path
@@ -128,15 +132,32 @@
 
 
 def count_lines(text: str) -> int:
+    """
+    Count the number of lines in a string.
+    :param text: The string to count the lines of.
+    :return: The number of lines.
+    """
+
     return len(text.splitlines())
 
 
 def first_n_lines(text: str, n: int) -> str:
+    """
+    Get the first n lines of a string.
+    :param text: The string to get the first n lines of.
+    :param n: The number of lines to get.
+    :return: The first n lines of the string.
+    """
+
     lines = text.splitlines()
     return "\n".join(lines[0:n])
 
 
-def process(file: Path):
+def process(file: Path) -> None:
+    """
+    Process the file, adding or updating the header if necessary.
+    :param file: The file to process.
+    """
     if (
         file.suffix in (".cpp", ".hpp")  # C++ Source / Header
         or file.name == "cpp.hint"  # C++ Hint file
@@ -189,7 +210,12 @@ def process(file: Path):
             f.write(contents)
 
 
-def walk_into_directory(path: Path):
+def walk_into_directory(path: Path) -> None:
+    """
+    Walk into the directory and process all files.
+    :param path: The directory to walk
+    """
+
     for subpath in path.rglob("*"):
         if subpath.is_file():
             process(subpath)

tools/benchmark.py

@@ -20,6 +20,10 @@
 #  SOFTWARE.                                                                                        #
 #####################################################################################################
 
+"""
+Benchmarking script for Steppable executables.
+"""
+
 import argparse
 import random
 import subprocess
@@ -32,7 +36,7 @@
 BUILD_PATH_DEFAULT = "build"
 
 FUNCTIONS = {
-    "abs": lambda x, y: abs(x),
+    "abs": lambda x, _: abs(x),
     "add": lambda x, y: x + y,
     "comparison": lambda x, y: x > y,
     "division": lambda x, y: x / y,
@@ -48,6 +52,14 @@ def _benchmark_function(
     input_1: int,
     input_2: int,
 ) -> float:
+    """
+    Benchmark a Python function.
+    :param function: The function to benchmark.
+    :param input_1: The first input.
+    :param input_2: The second input.
+    :return: The time taken to run the function.
+    """
+
     start = time.time()
     try:
         function(input_1, input_2)
@@ -65,6 +77,16 @@ def _benchmark(
     verbose: bool = False,
     timeout: int = 10,
 ) -> float:
+    """
+    Benchmark a system executable.
+    :param cmd: The executable to run.
+    :param input_str1: The first input.
+    :param input_str2: The second input.
+    :param verbose: Whether to print the output.
+    :param timeout: The timeout for the process.
+    :return: The time taken to run the executable.
+    """
+
     start = time.time()
     try:
         result = subprocess.run(
@@ -92,6 +114,16 @@ def _benchmark(
 def benchmark(
     cmd: str, inputs: List[str], limit: int, verbose: bool = False, timeout: int = 10
 ) -> Tuple[List[float], List[float], bool]:
+    """
+    Benchmark a Steppable executable.
+    :param cmd: The executable to run.
+    :param inputs: The inputs to run the executable on.
+    :param limit: The limit for the inputs.
+    :param verbose: Whether to print the output.
+    :param timeout: The timeout for the process.
+    :return: The time taken to run the executable.
+    """
+
     random_number = random.randint(0, limit)
     random_number_str = str(random_number)
     time_needed = []
@@ -114,7 +146,11 @@ def benchmark(
     return time_needed, time_needed_system, system_available
 
 
-def main():
+def main() -> None:
+    """
+    Main function for the benchmarking script.
+    """
+
     parser = argparse.ArgumentParser(
         prog="benchmark.py",
         description="Performs benchmarks on Steppable executables",

tools/building/compiler_detection.py

@@ -78,6 +78,7 @@ def get_identification(compiler_path: Path, compiler_type: int) -> str:
 def register_compiler(path: Path) -> None:
     """
     Adds the compiler path to the status.json file in the build directory. This is used to cache the compiler path.
+    :param path: The path to the compiler executable.
     """
     with open(BUILD_DIR / "status.json", "w") as f:
         json.dump({"compiler": str(path)}, f)

tools/building/project.py

@@ -338,6 +338,8 @@ def add_component(self, group: str, name: str) -> None:
         """
         Adds a component to the project. Components are the building blocks of the project, and are linked together to
         build the final executables.
+        :param group: The group to which the component belongs.
+        :param name: The name of the component.
         """
 
         files = [

tools/generate_changelog.py

@@ -0,0 +1,49 @@
+import subprocess
+from typing import List
+
+
+def get_commits() -> List[str]:
+    """
+    Get the commits between the main and develop branches.
+    :return: A list of commits.
+    """
+
+    # git log main..develop --pretty="%B" --reverse
+    try:
+        output = subprocess.check_output(
+            ["git", "log", "main..develop", "--pretty=%B#", "--reverse"],
+            universal_newlines=True,
+        )
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: {e}")
+        return []
+    except FileNotFoundError:
+        print(f"ERROR: Git not found on the system.")
+        return []
+
+    # Do some processing, ie. split the output into a list of commits
+    lines = output.split("\n#")
+    commits = [line.strip() for line in lines if line.strip()]
+
+    return commits
+
+
+def process_changelog() -> None:
+    """
+    Generate a changelog from the commits between the main and develop branches.
+    """
+
+    print("INFO: Generating changelog")
+    commits = get_commits()
+
+    for commit in commits:
+        lines = commit.split("\n")
+        print(f"- **{lines[0]}**")
+        lines.pop(0)
+
+        for line in lines:
+            print(f"  {line}")
+
+
+if __name__ == "__main__":
+    process_changelog()

tools/new_component.py

@@ -92,6 +92,10 @@
 
 
 def show_help() -> None:
+    """
+    Show the help text for new contributors.
+    """
+
     for idx, part in enumerate(HELP):
         print(part)
         if idx != (len(HELP) - 1):
@@ -107,6 +111,11 @@ def show_help() -> None:
 
 
 def validate_name(name: str) -> bool:
+    """
+    Validate the name of the component. It cannot contain restricted characters.
+    :param name: The name of the component.
+    :return: True if the name is valid, False otherwise.
+    """
     if (
         "*" in name
         or '"' in name
@@ -124,6 +133,12 @@ def validate_name(name: str) -> bool:
 
 
 def make_dir(name: str, date: str, author: str) -> None:
+    """
+    Create a new directory for the component.
+    :param name: The name of the component.
+    :param date: The date of creation.
+    :param author: The author of the component.
+    """
     path: Path = SRC_DIR / name
 
     if not path.is_dir():
@@ -305,6 +320,10 @@ def make_dir(name: str, date: str, author: str) -> None:
 
 
 def patch_cmakelists(name: str) -> None:
+    """
+    Patch the CMakeLists.txt file to include the new component.
+    :param name: The name of the component.
+    """
     with open(PROJECT_PATH / "CMakeLists.txt") as f:
         contents = f.read()
 
@@ -318,7 +337,11 @@ def patch_cmakelists(name: str) -> None:
 def ordinal(n: int) -> str:
     """
     Get the ordinal numeral for a given number n.
+    :param n: The number.
+    :return: The ordinal numeral.
     """
+
+    # Credits to https://stackoverflow.com/a/20007730/14868780 for this crazy one-liner.
     return f"{n:d}{'tsnrhtdd'[(n // 10 % 10 != 1) * (n % 10 < 4) * n % 10::4]}"
 
 
@@ -328,6 +351,10 @@ def ordinal(n: int) -> str:
 
 
 def main():
+    """
+    Main function for the new component wizard.
+    """
+
     print(WELCOME_STRING)
     selection = getch().upper()
 

tools/patch_compile_commands.py

@@ -71,7 +71,7 @@ def get_compile_commands() -> Path:
     raise RuntimeError("Cannot get the CMake build directory")
 
 
-def patch():
+def patch() -> None:
     """Remove the NO_MAIN definition in compile_commands.json."""
 
     try: