Add comprehensive inline documentation to all modules and enhance README

Co-authored-by: dwinkler1 <22460147+dwinkler1@users.noreply.github.com>

templates/rde/overlays/project-scripts.nix

@@ -1,14 +1,39 @@
 # Project scripts overlay
+#
+# This overlay wraps shell scripts from the scripts/ directory as Nix packages.
+# Scripts are made available as executable commands with the project name prefix.
+#
+# How it works:
+#   1. Reads shell scripts from scripts/ directory
+#   2. Substitutes @defaultPackageName@ with actual package name
+#   3. Creates executable packages via writeShellScriptBin
+#   4. Scripts become available as: <packageName>-<scriptName>
+#
+# Available scripts:
+#   - initPython: Initialize Python project with uv
+#   - initProject: Set up project directory structure
+#   - updateDeps: Update all dependencies (R, Python, Julia, flake)
+#   - activateDevenv: Activate devenv shell if available
+#
+# Usage: Scripts are automatically available in the dev shell
 config: final: prev: let
   # Helper function to substitute config placeholders in scripts
+  # Replaces @defaultPackageName@ with the actual package name from config
   substituteScript = scriptPath:
     prev.lib.replaceStrings
       ["@defaultPackageName@"]
       [config.defaultPackageName]
       (builtins.readFile scriptPath);
 in {
+  # Python project initialization (creates pyproject.toml, adds packages)
   initPython = prev.writeShellScriptBin "initPython" (substituteScript ./scripts/initPython.sh);
+  
+  # Project structure setup (creates directories, git repo, .gitignore)
   initProject = prev.writeShellScriptBin "initProject" (substituteScript ./scripts/initProject.sh);
+  
+  # Update all dependencies (R packages, Python packages, flake inputs)
   updateDeps = prev.writeShellScriptBin "updateDeps" (substituteScript ./scripts/updateDeps.sh);
+  
+  # Activate devenv environment if devenv.nix exists
   activateDevenv = prev.writeShellScriptBin "activateDevenv" (substituteScript ./scripts/activateDevenv.sh);
 }

templates/rde/overlays/python.nix

@@ -1,7 +1,22 @@
 # Python packages overlay
+#
+# This overlay configures the Python environment with essential packages.
+# Note: Most Python packages should be managed via uv (pyproject.toml)
+# This overlay is for packages needed at the system level.
+#
+# Usage:
+#   - Add system-level Python packages to the list below
+#   - For project-specific packages, use uv (e.g., 'uv add package-name')
+#   - The Python interpreter is available via pkgs.python
+#
+# Example additions:
+#   - numpy, pandas, scipy for scientific computing
+#   - pytest, black, mypy for development tools
 final: prev: {
+  # Python 3 with system-level packages
   python = prev.python3.withPackages (pyPackages:
     with pyPackages; [
-      requests
+      requests  # HTTP library for making API calls
+      # Add more system-level packages here
     ]);
 }

templates/rde/overlays/r.nix

@@ -1,22 +1,39 @@
 # R packages overlay
+# 
+# This overlay configures the R environment with essential packages for data analysis.
+# It combines packages from rstats-on-nix (rpkgs) with custom packages.
+#
+# Usage:
+#   - Edit the package list below to add/remove R packages
+#   - Create r-packages.nix in your project root to add custom packages
+#   - Custom file format: rpkgs: with rpkgs.rPackages; [ package1 package2 ]
+#
+# The overlay exports:
+#   - quarto: Quarto with R packages
+#   - rWrapper: R executable with all packages available
 final: prev: let
+  # Core R packages for data analysis and development
   reqPkgs = with final.rpkgs.rPackages;
     [
-      broom
-      data_table
-      janitor
-      languageserver
-      reprex
-      styler
-      tidyverse
+      broom         # Tidy model outputs
+      data_table    # Fast data manipulation
+      janitor       # Data cleaning helpers
+      languageserver # LSP for IDE support
+      reprex        # Reproducible examples
+      styler        # Code formatting
+      tidyverse     # Data science ecosystem
     ]
+    # Additional packages from fran overlay
     ++ (with final.extraRPackages; [
-      httpgd
+      httpgd        # HTTP graphics device for interactive plots
     ])
     # Import custom R packages from project root if file exists
     # Users can create r-packages.nix in their project to add more packages
+    # Example r-packages.nix: rpkgs: with rpkgs.rPackages; [ ggplot2 dplyr ]
     ++ (prev.lib.optional (builtins.pathExists ./r-packages.nix) (import ./r-packages.nix final.rpkgs));
 in {
+  # Quarto with R support and all required packages
   quarto = final.rpkgs.quarto.override {extraRPackages = reqPkgs;};
+  # R wrapper with all packages pre-loaded
   rWrapper = final.rpkgs.rWrapper.override {packages = reqPkgs;};
 }

templates/rde/overlays/rix.nix

@@ -1,4 +1,21 @@
 # Rix overlay for R packages from rstats-on-nix
+#
+# This overlay provides access to R packages from the rstats-on-nix project.
+# rstats-on-nix maintains snapshots of CRAN packages built with Nix.
+#
+# Purpose:
+#   - Provides reproducible R package versions
+#   - Ensures binary cache availability for faster builds
+#   - Maintained by the rstats-on-nix community
+#
+# The rpkgs attribute gives access to:
+#   - rpkgs.rPackages: All CRAN packages
+#   - rpkgs.quarto: Quarto publishing system
+#   - rpkgs.rWrapper: R with package management
+#
+# Update the R snapshot date in flake.nix inputs section:
+#   rixpkgs.url = "github:rstats-on-nix/nixpkgs/YYYY-MM-DD"
 inputs: final: prev: {
+  # R packages from rstats-on-nix for the current system
   rpkgs = inputs.rixpkgs.legacyPackages.${prev.stdenv.hostPlatform.system};
 }

templates/rde/overlays/theme.nix

@@ -1,12 +1,30 @@
 # Extra theme packages overlay
+#
+# This overlay configures the Neovim color scheme based on user configuration.
+# It transforms the theme config from flake.nix into a Neovim plugin structure.
+#
+# Usage:
+#   - Configure theme in flake.nix config.theme section
+#   - Specify colorscheme name, background (dark/light)
+#   - Add custom Lua configuration in extraColorschemePackage
+#
+# The overlay exports:
+#   - extraTheme: Plugin structure with theme configuration
+#
+# Built-in themes: cyberdream, onedark, tokyonight, kanagawa
 config: final: prev: let
+  # Transform user theme config into Neovim plugin format
   extraTheme = {
+    # Get the plugin package from nixpkgs
     plugin = prev.vimPlugins."${config.theme.extraColorschemePackage.plugin}";
+    # Theme name for identification
     name = config.theme.extraColorschemePackage.name;
+    # Lua configuration to run when theme loads
     config = {
       lua = config.theme.extraColorschemePackage.extraLua;
     };
   };
 in {
+  # Export theme for use in Neovim configuration
   inherit extraTheme;
 }