Added comments and cleaned up python source code

core/source/generation/readme_generator.py

@@ -1,8 +1,7 @@
-from tableofcontents_generator import generate_table_of_contents
 from contents_generator import generate_contents
 from mainheader_generator import generate_mainheader
+from tableofcontents_generator import generate_table_of_contents
 
-# List of target platforms
 platforms = ["all", "windows", "macos", "linux", "selfhost"]
 
 # Platforms mapped to corresponding header files
@@ -19,27 +18,22 @@ def generate_readme_for_platform(platform):
     content = ""
     header_file = header_files.get(platform, "core/components/header.md")
 
-    # Inject mainheader with dynamic project count
+    # Inject every component of the list from top to bottom
     if platform == "all":
         content += generate_mainheader()
 
-    # Inject header
     with open(header_file, "r", encoding="utf-8") as f:
         content += f.read() + "\n"
 
-    # Inject tags.md
     with open("core/components/tags.md", "r", encoding="utf-8") as f:
         content += f.read() + "\n"
 
-    # Generate Table of Contents
     toc_md = generate_table_of_contents()
     content += toc_md + "\n"
 
-    # Generate the actual markdown list of contents for the given platform
     contents_md = generate_contents(platform)
     content += contents_md + "\n"
 
-    # Inject footer.md
     with open("core/components/footer.md", "r", encoding="utf-8") as f:
         content += f.read() + "\n"
 

core/source/generation/tableofcontents_generator.py

@@ -1,13 +1,12 @@
 import json
 
 
+# Utils
 def slugify(name):
-    # Create an anchor-friendly slug from a string
     return name.lower().replace(" ", "-").replace("(", "").replace(")", "")
 
 
 def generate_table_of_contents():
-    # Load the categories JSON data
     with open("core/data/static/categories.json", "r", encoding="utf-8") as f:
         data = json.load(f)
     categories = data.get("categories", [])
@@ -21,17 +20,16 @@ def generate_table_of_contents():
         alphabetical_md += f"- [{name}](#{slugify(name)})\n"
 
     # Build the categorized list
-    # Create a mapping from parent id to parent name
     parent_map = {cat["id"]: cat["name"] for cat in categories}
-    # Group subcategories by their parent id
+
     grouped = {}
     for sub in subcategories:
         parent = sub.get("parent", "other")
         grouped.setdefault(parent, []).append(sub["name"])
-    # Sort each group's subcategories alphabetically
+
     for key in grouped:
         grouped[key].sort(key=lambda x: x.lower())
-    # Sort parent categories (exclude "other", which is appended at the end)
+
     parents = [(pid, parent_map.get(pid, "Other")) for pid in grouped if pid != "other"]
     parents.sort(key=lambda x: x[1].lower())
     if "other" in grouped:
@@ -64,7 +62,7 @@ def generate_table_of_contents():
 
 <details open>
   <summary><b>Categorized</b></summary> <br />
-  
+
 {categorized_md}
 </details>
 """

core/source/maintenance/json_formatter.py

@@ -14,6 +14,7 @@ with open("core/data/static/platforms.json") as f:
 seen_github = set()
 issues_report = []
 
+# Check for formatting issues inside of all data files (static and dynamic)
 for app in applications:
     app_issues = []
 

core/source/maintenance/stats_updator.py

@@ -1,8 +1,9 @@
-import os
-import requests
 import json
+import os
 from datetime import datetime
 
+import requests
+
 with open("core/data/dynamic/applications.json", "r") as f:
     data = json.load(f)
 
@@ -14,6 +15,7 @@ headers = {
 }
 
 
+# Update stats of all projects by contacting GitHub API
 def update_application_data(app):
     repo_name = app["repo_url"].split("github.com/")[1]
 
@@ -30,6 +32,7 @@ def update_application_data(app):
         app["stars"] = repo_data.get("stargazers_count", app["stars"])
         app["language"] = repo_data.get("language", app["language"])
 
+        # Check for flags to prevent update of specific stats
         if "custom-homepage" not in app.get("flags", []):
             app["homepage_url"] = repo_data.get("homepage", app["homepage_url"])
 

core/source/maintenance/status_checker.py

@@ -1,8 +1,9 @@
-import os
-import requests
 import json
+import os
 from datetime import datetime, timedelta
 
+import requests
+
 INPUT_FILE = "core/data/dynamic/applications.json"
 OUTPUT_FILE = "resources/maintenance/status_maintenance.md"
 GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
@@ -18,6 +19,7 @@ potentially_abandoned = []
 archived = []
 no_longer_exists = []
 
+# Check if projects are abandoned, archived, or no longer exist
 for app in data.get("applications", []):
     repo_url = app.get("repo_url")
     if not repo_url or "github.com" not in repo_url: