cleanup and refactoring

raytracer/nvpro_core/docgen.py

@@ -0,0 +1,95 @@
+# This script generates a README.md file for each folder containing header files, 
+# with a table of contents and documentation extracted from the header files.
+
+# How to use:
+# 1. Customize the excluded_folders list as per your project's needs.
+# 2. Run the script in the root directory of your project.
+
+# Note: To include documentation in the README.md file, enclose the documentation 
+# within the "@DOC_START" and "@DOC_END" tags in the header files. Anything inside
+# will be threated as Markdown documentation. 
+# If the header contains @DOC_SKIP, the header will not try to generate documentation
+
+# Note: Any title (`#`) will be demoted by two level to fit the documentation.
+#       Level-1 (title): reserve, level-2 (sub-title): filename
+#       Ex. "# MyClass"  -> "### MyClass"
+
+import os
+
+# Define excluded folders
+excluded_folders = [
+    ".git",
+    ".vscode",
+    "cmake",
+    "doxygen",
+    "resources",
+    "third_party",
+    "KHR",
+    "GL",
+    "OV",
+    "PACKAGE-LICENSES",
+    "_autogen"
+]
+
+# Function to generate table of contents
+def generate_table_of_contents(header_files):
+    return "## Table of Contents\n" + "\n".join(f"- [{file}](#{file.replace('.', '')})" for file in header_files)
+
+# Function to extract documentation from header files
+def extract_documentation(file_path):
+    documentation = ""
+    with open(file_path, 'r', encoding="utf-8") as file:
+        in_doc_block = False
+        for line in file:
+            if "@DOC_START" in line.strip():
+                in_doc_block = True
+            elif "@DOC_END" in line.strip():
+                in_doc_block = False
+            elif in_doc_block:
+                if line.lstrip().startswith("# "):
+                    documentation += "##" + line.lstrip() + "\n"
+                else:
+                    documentation += line.strip() + "\n"
+    if not documentation:
+        documentation = "\n> Todo: Add documentation\n"
+    return documentation
+
+
+# Traverse through folders
+for root, dirs, files in os.walk("."):
+    print("Parsing sub-folder:", root)  # Print the sub-folder being parsed
+
+    # Exclude specified folders
+    dirs[:] = [d for d in dirs if d not in excluded_folders]
+
+    # Filter header files
+    header_files = []
+    for file in files:
+        if file.endswith((".h", ".hpp")):
+            with open(os.path.join(root, file), encoding="utf-8") as f:
+                # Check for "@DOC_SKIP" only if file extension matches
+                if not any("@DOC_SKIP" in line for line in f):
+                    header_files.append(file)
+                else:
+                    # Optional: Inform about skipping files (for clarity)
+                    print(f" - Skipping file: {file}")  # Informative, optional
+
+    # Proceed if there are header files
+    if header_files:
+        # Generate table of contents
+        table_of_contents = generate_table_of_contents(header_files)
+
+        # Create or append to README.md
+        with open(os.path.join(root, "README.md"), "w") as readme:
+            readme.write(table_of_contents + "\n")
+
+            # Process each header file
+            for header_file in header_files:
+                readme.write(f"\n## {header_file}\n")
+                header_path = os.path.join(root, header_file)
+
+                # Extract documentation from header file
+                documentation = extract_documentation(header_path)
+
+                # Append documentation to README.md
+                readme.write(documentation)