Better comments

src/py/css_generator.py

@@ -3,6 +3,7 @@ from pathlib import Path
 from shutil import copyfile
 
 def generate_css_variables(colors_dict, output_path):
+    """Generate css variables for theme colors"""
     css_lines = [":root {"]
     for key, value in colors_dict.items():
         css_lines.append(f"  --color-{key.replace('_', '-')}: {value};")
@@ -13,6 +14,7 @@ def generate_css_variables(colors_dict, output_path):
     logging.info(f"[✓] CSS variables written to {output_path}")
 
 def generate_fonts_css(fonts_dir, output_path, fonts_cfg=None):
+    """Generate css variables fonts"""
     font_files = list(fonts_dir.glob("*"))
     font_faces = {}
     preload_links = []
@@ -57,6 +59,7 @@ def generate_fonts_css(fonts_dir, output_path, fonts_cfg=None):
     return preload_links
 
 def generate_google_fonts_link(fonts):
+    """Generate src link for Google fonts"""
     if not fonts:
         return ""
     families = []

src/py/gallery_builder.py

@@ -10,6 +10,7 @@ GALLERY_DIR = Path("config/photos/gallery")
 HERO_DIR = Path("config/photos/hero")
 
 def load_yaml(path):
+    """Load gallery config .yaml file"""
     print(f"[→] Loading {path}...")
     if not os.path.exists(path):
         print(f"[✗] File not found: {path}")
@@ -21,11 +22,13 @@ def load_yaml(path):
         return data
 
 def save_yaml(data, path):
+    """Save modified gallery config .yaml file"""
     with open(path, "w", encoding="utf-8") as f:
         yaml.dump(data, f, sort_keys=False, allow_unicode=True)
     print(f"[✓] Saved updated YAML to {path}")
 
 def get_all_image_paths(directory):
+    """Get the path to record for builded site"""
     return sorted([
         str(p.relative_to(directory.parent)).replace("\\", "/")
         for p in directory.rglob("*")
@@ -33,6 +36,7 @@ def get_all_image_paths(directory):
     ])
 
 def update_gallery():
+    """Update the gallery photo list"""
     print("\n=== Updating gallery.yaml (gallery section) ===")
     gallery = load_yaml(GALLERY_YAML)
 
@@ -71,6 +75,7 @@ def update_gallery():
         print("[✓] No changes to gallery.yaml (gallery)")
 
 def update_hero():
+    """Update the hero photo list"""
     print("\n=== Updating gallery.yaml (hero section) ===")
     gallery = load_yaml(GALLERY_YAML)
 

src/py/html_generator.py

@@ -3,6 +3,7 @@ import logging
 from pathlib import Path
 
 def render_template(template_path, context):
+    """Render html templates"""
     with open(template_path, encoding="utf-8") as f:
         content = f.read()
     for key, value in context.items():
@@ -11,6 +12,7 @@ def render_template(template_path, context):
     return content
 
 def render_gallery_images(images):
+    """Render the photo gallery"""
     html = ""
     for img in images:
         tags = " ".join(img.get("tags", []))
@@ -24,6 +26,7 @@ def render_gallery_images(images):
     return html
 
 def generate_gallery_json_from_images(images, output_dir):
+    """Generte the hero carrousel photo list"""
     try:
         img_list = [img["src"] for img in images]
         output_path = output_dir / "data" / "gallery.json"
@@ -35,6 +38,7 @@ def generate_gallery_json_from_images(images, output_dir):
         logging.error(f"[✗] Error generating gallery JSON: {e}")
 
 def generate_robots_txt(canonical_url, allowed_paths, output_dir):
+    """Generate the robot.txt"""
     robots_lines = ["User-agent: *"]
 
     # Block everything by default
@@ -62,6 +66,7 @@ def generate_robots_txt(canonical_url, allowed_paths, output_dir):
         logging.error(f"[✗] Failed to write robots.txt: {e}")
 
 def generate_sitemap_xml(canonical_url, allowed_paths, output_dir):
+    """Generate the sitemap"""
     urlset_start = '<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
     urlset_end = '</urlset>\n'
     urls = ""

src/py/utils.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from shutil import copytree, rmtree, copyfile
 
 def load_yaml(path):
+    """Load gallery and site .yaml conf"""
     if not path.exists():
         logging.warning(f"[!] YAML file not found: {path}")
         return {}
@@ -11,6 +12,7 @@ def load_yaml(path):
         return yaml.safe_load(f)
 
 def load_theme_config(theme_name, themes_dir):
+    """Load theme.yaml"""
     theme_dir = themes_dir / theme_name
     theme_config_path = theme_dir / "theme.yaml"
     if not theme_config_path.exists():
@@ -20,26 +22,25 @@ def load_theme_config(theme_name, themes_dir):
     return theme_vars, theme_dir
 
 def clear_dir(path: Path):
+    """Clear the output dir"""
     if not path.exists():
         path.mkdir(parents=True)
         return
-
-    # Remove all files and subdirectories inside path, but not path itself
     for child in path.iterdir():
         if child.is_file() or child.is_symlink():
-            child.unlink()  # delete file or symlink
+            child.unlink()
         elif child.is_dir():
-            rmtree(child)  # delete directory and contents
+            rmtree(child)
-
-# Then replace your ensure_dir with this:
 
 def ensure_dir(path: Path):
+    """Create the output dir if it does not exist"""
     if not path.exists():
         path.mkdir(parents=True)
     else:
         clear_dir(path)
 
 def copy_assets(js_dir, style_dir, build_dir):
+    """Copy public assets to output dir"""
     for folder in [js_dir, style_dir]:
         if folder.exists():
             dest = build_dir / folder.name