Add comprehensive inline documentation to all modules and enhance README

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

templates/rde/README.md

@@ -1,6 +1,47 @@
 # Research Development Environment (RDE) Template
 
-This is a Nix flake template for setting up research development environments with support for R, Python, and Julia.
+A modular Nix flake template for reproducible research environments with support for R, Python, and Julia. Designed for data science, statistical analysis, and computational research.
+
+## Features
+
+- 🔬 **Multi-language support**: R, Python, Julia with integrated tooling
+- 📦 **Reproducible**: Nix ensures consistent environments across machines
+- 🎨 **Neovim-based**: Powerful editor with LSP, completion, and more
+- 📊 **Research-focused**: Pre-configured for data analysis workflows
+- 🔧 **Modular**: Enable only the languages you need
+- 📝 **Documented**: Comprehensive inline documentation
+
+## Quick Start
+
+### Installation
+
+```bash
+# Initialize a new project with this template
+nix flake init -t github:dwinkler1/np#rde
+
+# Enter the development environment
+nix develop
+
+# Or use direnv for automatic activation
+echo "use flake" > .envrc
+direnv allow
+```
+
+### First Steps
+
+```bash
+# Initialize project structure (creates directories, git repo)
+p-initProject
+
+# Enable Python (if needed)
+# Edit flake.nix: set enabledLanguages.python = true
+
+# Initialize Python project
+p-initPython
+
+# Update all dependencies
+p-updateDeps
+```
 
 ## Structure
 
@@ -8,7 +49,8 @@ The template is organized into several directories for better maintainability:
 
 ```
 templates/rde/
-├── flake.nix              # Main flake configuration (258 lines)
+├── flake.nix              # Main flake configuration (261 lines)
+├── README.md              # This file
 ├── overlays/              # Nix overlays for packages
 │   ├── r.nix             # R packages configuration
 │   ├── python.nix        # Python packages configuration
@@ -22,7 +64,8 @@ templates/rde/
 │   ├── r.nix             # R commands
 │   └── utils.nix         # Utility commands (initProject, etc.)
 ├── lib/                   # Helper functions
-│   └── shell-hook.nix    # Dev shell welcome message
+│   ├── shell-hook.nix    # Dev shell welcome message
+│   └── mini-notify-config.lua # Neovim notification filtering
 └── scripts/               # Shell scripts
     ├── initPython.sh     # Initialize Python project
     ├── initProject.sh    # Initialize project structure
@@ -30,32 +73,274 @@ templates/rde/
     └── activateDevenv.sh # Activate devenv shell
 ```
 
+## Configuration
+
+Edit the `config` section in `flake.nix` to customize your environment:
+
+### Basic Settings
+
+```nix
+config = rec {
+  # Name for your project commands (e.g., myproject-r, myproject-py)
+  defaultPackageName = "p";
+  
+  # Enable/disable language support
+  enabledLanguages = {
+    julia = false;   # Julia with Pluto notebooks
+    python = false;  # Python with uv package manager
+    r = true;        # R with tidyverse and friends
+  };
+  
+  # Additional features
+  enabledPackages = {
+    gitPlugins = enabledLanguages.r;  # R.nvim plugin
+    devenv = false;                    # Additional dev environment
+  };
+  
+  # Neovim color scheme
+  theme = rec {
+    colorscheme = "kanagawa";  # cyberdream, onedark, tokyonight, kanagawa
+    background = "dark";       # dark or light
+  };
+};
+```
+
+### Language-Specific Configuration
+
+#### R Configuration
+
+Edit `overlays/r.nix` to add/remove R packages:
+
+```nix
+reqPkgs = with final.rpkgs.rPackages; [
+  tidyverse      # Add your packages here
+  data_table
+  # ... more packages
+];
+```
+
+Or create `r-packages.nix` in your project:
+
+```nix
+rpkgs: with rpkgs.rPackages; [
+  ggplot2
+  dplyr
+]
+```
+
+#### Python Configuration
+
+Python packages are managed via `uv`:
+
+```bash
+# Add packages to your project
+uv add numpy pandas matplotlib
+
+# Or edit pyproject.toml directly
+```
+
+#### Julia Configuration
+
+Julia packages use the built-in package manager:
+
+```bash
+# In Julia REPL (p-jl)
+using Pkg
+Pkg.add("DataFrames")
+```
+
+## Available Commands
+
+Commands are prefixed with your `defaultPackageName` (default: `p`).
+
+### Editor
+
+- `p` or `p-pvim`: Launch Neovim
+- `p-g`: Launch Neovide (GUI)
+
+### R (when enabled)
+
+- `p-r`: R console with pre-loaded packages
+- Includes: tidyverse, data.table, languageserver, quarto
+
+### Python (when enabled)
+
+- `p-py`: Python interpreter
+- `p-ipy`: IPython REPL (enhanced interactive shell)
+- `p-marimo`: Marimo notebooks (reactive notebooks)
+- `p-initPython`: Initialize Python project with uv
+
+### Julia (when enabled)
+
+- `p-jl`: Julia REPL with project environment
+- `p-pluto`: Pluto.jl notebooks (reactive notebooks)
+- `p-initJl`: Initialize Julia project
+
+### Utilities
+
+- `p-initProject`: Create project directory structure
+- `p-updateDeps`: Update all dependencies (R, Python, Julia, flake)
+
+## Project Workflow
+
+### 1. Initialize Project
+
+```bash
+# Create standardized directory structure
+p-initProject
+
+# Creates:
+# - data/{raw,processed,interim}/
+# - docs/
+# - figures/
+# - tables/
+# - src/{analysis,data_prep,explore,utils}/
+# - .gitignore
+# - README.md
+```
+
+### 2. Set Up Language Environment
+
+**For R:**
+```bash
+# R is enabled by default
+# Just start using it
+p-r
+```
+
+**For Python:**
+```bash
+# 1. Enable in flake.nix
+# 2. Initialize project
+p-initPython
+# 3. Add packages
+uv add numpy pandas scikit-learn
+```
+
+**For Julia:**
+```bash
+# 1. Enable in flake.nix
+# 2. Initialize project
+p-initJl
+# 3. Packages are managed in Julia REPL
+```
+
+### 3. Development
+
+```bash
+# Start Neovim
+p
+
+# Or use notebooks
+p-marimo          # Python notebooks
+p-pluto           # Julia notebooks
+
+# R scripts work with p (Neovim has R support)
+```
+
+### 4. Keep Dependencies Updated
+
+```bash
+# Update everything at once
+p-updateDeps
+
+# This updates:
+# - R packages (rixpkgs snapshot)
+# - Python packages (via uv)
+# - Julia packages (via Pkg)
+# - Flake inputs
+```
+
 ## Benefits of This Structure
 
 1. **Modularity**: Each component is in its own file, making it easier to understand and modify
 2. **Maintainability**: Changes to one language or feature don't affect others
-3. **Readability**: Main flake.nix is now ~258 lines instead of 688 (62.5% reduction)
+3. **Readability**: Main flake.nix is ~261 lines instead of 688 (62% reduction)
 4. **Reusability**: Individual modules can be easily reused or replaced
 5. **Testability**: Smaller files are easier to test and debug
+6. **Documentation**: Comprehensive inline comments explain how everything works
 
-## Configuration
+## Extending the Template
 
-Edit the `config` section in `flake.nix` to customize:
+### Add New R Packages
 
-- `defaultPackageName`: Name of your project/package
+**System-wide** (edit `overlays/r.nix`):
-- `enabledLanguages`: Enable/disable R, Python, Julia support
+```nix
-- `enabledPackages`: Enable additional features like devenv
+reqPkgs = with final.rpkgs.rPackages; [
-- `theme`: Configure Neovim color scheme
+  tidyverse
+  yourNewPackage  # Add here
+];
+```
 
-## Extending
+**Project-specific** (create `r-packages.nix`):
+```nix
+rpkgs: with rpkgs.rPackages; [
+  projectSpecificPackage
+]
+```
 
-To add new functionality:
+### Add New Python Packages
 
-- **New packages**: Add overlays in `overlays/`
+```bash
-- **New commands**: Add host configs in `hosts/`
+uv add package-name
-- **New scripts**: Add shell scripts in `scripts/`
+```
-- **New languages**: Create new host and overlay files
+
-- **Modify shell welcome**: Edit `lib/shell-hook.nix`
+### Add New Commands
+
+Edit the appropriate file in `hosts/`:
+- `hosts/python.nix` - Python commands
+- `hosts/julia.nix` - Julia commands
+- `hosts/r.nix` - R commands
+- `hosts/utils.nix` - General utilities
+
+### Add New Scripts
+
+1. Create script in `scripts/`
+2. Add to `overlays/project-scripts.nix`
+3. Add to appropriate host file
+
+### Customize Neovim
+
+The template uses a pre-configured Neovim (nixCats). To customize:
+- Edit theme in `config.theme` section
+- Add plugins in `flake.nix` categoryDefinitions
+- Modify LSP settings in `categoryDefinitions.lspsAndRuntimeDeps`
+
+## Troubleshooting
+
+### Nix Build Fails
+
+```bash
+# Update flake inputs
+nix flake update
+
+# Clear cache
+nix-collect-garbage
+```
+
+### Python Packages Not Found
+
+```bash
+# Sync environment
+uv sync
+
+# Or re-initialize
+p-initPython
+```
+
+### R Packages Not Available
+
+```bash
+# Update R snapshot
+p-updateDeps
+
+# Or check overlays/r.nix for package name
+```
+
+## Related Documentation
+
+- [REFACTORING.md](REFACTORING.md) - Technical details about the modular structure
+- [SUMMARY.md](SUMMARY.md) - Metrics and comparison with original template
 
 ## Usage
 

templates/rde/hosts/default.nix

@@ -1,8 +1,27 @@
 # Merges all host configurations from separate modules
+#
+# This file combines host definitions from language-specific modules.
+# It serves as the single entry point for all command definitions.
+#
+# Structure:
+#   - python.nix: Python commands (marimo, ipy, py, initPython)
+#   - julia.nix: Julia commands (jl, pluto, initJl)
+#   - r.nix: R commands (r console)
+#   - utils.nix: Utility commands (initProject, updateDeps, etc.)
+#
+# Usage:
+#   This file is imported in flake.nix:
+#   hosts = import ./hosts config pkgs;
+#
+# The merged result provides all commands in a single attribute set.
+# Commands are enabled/disabled based on config.enabledLanguages settings.
 config: pkgs: let
+  # Import individual host modules
   pythonHosts = import ./python.nix config pkgs;
   juliaHosts = import ./julia.nix config pkgs;
   rHosts = import ./r.nix config pkgs;
   utilsHosts = import ./utils.nix config pkgs;
 in
+  # Merge all hosts into single attribute set
+  # Later definitions override earlier ones in case of conflicts
   pythonHosts // juliaHosts // rHosts // utilsHosts

templates/rde/hosts/julia.nix

@@ -1,5 +1,28 @@
 # Julia-related host configurations
+#
+# This module defines all Julia-related commands available in the dev shell.
+# Julia is configured with project-local package management.
+#
+# Available commands (when Julia is enabled):
+#   - <name>-jl: Launch Julia REPL with project environment
+#   - <name>-pluto: Launch Pluto.jl notebook server
+#   - <name>-initJl: Initialize Julia project and install Pluto
+#
+# How it works:
+#   - All commands use --project=. to activate local Project.toml
+#   - JULIA_NUM_THREADS=auto enables multi-threading
+#   - Packages are managed via Julia's built-in Pkg manager
+#
+# Project setup:
+#   1. Run <name>-initJl to create Project.toml
+#   2. Add packages: julia --project=. -e 'using Pkg; Pkg.add("PackageName")'
+#   3. Packages are stored in Project.toml and Manifest.toml
+#
+# Dependencies: julia-bin (configured in flake.nix)
 config: pkgs: {
+  # jl: Julia REPL with project environment
+  # Activates local Project.toml for package management
+  # Use Pkg.add("PackageName") to install packages
   jl = {
     enable = config.enabledLanguages.julia;
     path = {
@@ -8,6 +31,9 @@ config: pkgs: {
     };
   };
 
+  # initJl: Initialize Julia project
+  # Creates Project.toml and installs Pluto.jl notebook
+  # Run this once to set up Julia package management
   initJl = {
     enable = config.enabledLanguages.julia;
     path = {
@@ -16,6 +42,10 @@ config: pkgs: {
     };
   };
 
+  # pluto: Launch Pluto.jl interactive notebook
+  # Auto-installs Pluto if not present in Project.toml
+  # Opens browser with notebook interface
+  # Notebooks are reactive - cells update automatically
   pluto = let
     runPluto = ''
       import Pkg; import TOML; Pkg.instantiate();

templates/rde/hosts/python.nix

@@ -1,5 +1,23 @@
 # Python-related host configurations
+#
+# This module defines all Python-related commands available in the dev shell.
+# Each command is configured with enable conditions and execution paths.
+#
+# Available commands (when Python is enabled):
+#   - <name>-marimo: Launch Marimo notebook (interactive Python notebooks)
+#   - <name>-py: Run Python interpreter
+#   - <name>-ipy: Launch IPython REPL (enhanced interactive shell)
+#   - <name>-initPython: Initialize Python project with uv
+#
+# How it works:
+#   - Commands are enabled based on config.enabledLanguages.python
+#   - UV (Python package manager) handles project dependencies
+#   - Each command auto-initializes project if pyproject.toml doesn't exist
+#
+# Dependencies: uv, python, nodejs, basedpyright (configured in flake.nix)
 config: pkgs: {
+  # Marimo: Interactive notebook environment for Python
+  # Auto-initializes UV project and installs marimo on first run
   marimo = let
     marimoInit = ''
       set -euo pipefail
@@ -33,6 +51,8 @@ config: pkgs: {
     };
   };
 
+  # py: Standard Python interpreter
+  # Direct access to Python REPL for quick experiments
   py = {
     enable = config.enabledLanguages.python;
     path = {
@@ -40,6 +60,9 @@ config: pkgs: {
     };
   };
 
+  # ipy: IPython - Enhanced interactive Python shell
+  # Features: syntax highlighting, tab completion, magic commands
+  # Auto-initializes UV project and installs IPython on first run
   ipy = let
     ipythonInit = ''
       set -euo pipefail
@@ -75,6 +98,9 @@ config: pkgs: {
     };
   };
 
+  # initPython: Initialize Python project
+  # Creates pyproject.toml and adds IPython and Marimo
+  # Use this to set up Python tooling in an existing project
   initPython = {
     enable = config.enabledLanguages.python;
     path.value = "${pkgs.initPython}/bin/initPython";

templates/rde/hosts/r.nix

@@ -1,5 +1,26 @@
 # R-related host configurations
+#
+# This module defines R-related commands available in the dev shell.
+# R is configured with project-local package library and Quarto support.
+#
+# Available commands (when R is enabled):
+#   - <name>-r: Launch R console with packages
+#
+# How it works:
+#   - Uses rWrapper which includes all packages from overlays/r.nix
+#   - R_LIBS_USER=./.Rlibs enables project-local package installation
+#   - --no-save --no-restore ensures clean session startup
+#
+# Package management:
+#   - System packages: Edit overlays/r.nix
+#   - Project packages: Install with install.packages() in R
+#   - Custom packages: Create r-packages.nix in project root
+#
+# Dependencies: rWrapper, quarto, air-formatter (configured in flake.nix)
 config: pkgs: {
+  # r: R console with pre-configured packages
+  # Includes tidyverse, data.table, and other common packages
+  # Session starts without saving/restoring workspace
   r = {
     enable = config.enabledLanguages.r;
     path = {

templates/rde/hosts/utils.nix

@@ -1,5 +1,24 @@
 # Utility and common host configurations
+#
+# This module defines general-purpose commands and utilities.
+# These commands are available regardless of enabled languages.
+#
+# Available commands:
+#   - <name>: Launch Neovim editor (default command)
+#   - <name>-g: Launch Neovide (GUI for Neovim)
+#   - <name>-initProject: Initialize project directory structure
+#   - <name>-updateDeps: Update all dependencies (R, Python, Julia, flake)
+#   - <name>-initDevenv: Initialize devenv project (if enabled)
+#   - <name>-devenv: Run devenv commands (if enabled)
+#   - <name>-activateDevenv: Activate devenv shell (if enabled)
+#
+# Note: node, perl, ruby are also available but have minimal configuration
+#
+# Dependencies: neovide, devenv (if enabled), project scripts
 config: pkgs: {
+  # g: Neovide - GUI frontend for Neovim
+  # Provides smooth scrolling, animations, and GUI features
+  # Automatically connects to the configured Neovim instance
   g = {
     enable = true;
     path = {
@@ -11,6 +30,10 @@ config: pkgs: {
     };
   };
 
+  # initProject: Initialize research project structure
+  # Creates standardized directory layout for data analysis
+  # Sets up: data/, docs/, figures/, tables/, src/
+  # Also initializes git repository and .gitignore
   initProject = {
     enable = true;
     path = {
@@ -18,6 +41,9 @@ config: pkgs: {
     };
   };
 
+  # initDevenv: Initialize devenv project
+  # Devenv provides additional development environment features
+  # Only available if config.enabledPackages.devenv = true
   initDevenv = {
     enable = config.enabledPackages.devenv;
     path = {
@@ -26,6 +52,9 @@ config: pkgs: {
     };
   };
 
+  # activateDevenv: Activate devenv shell
+  # Automatically runs when entering dev shell if devenv.nix exists
+  # Only available if config.enabledPackages.devenv = true
   activateDevenv = {
     enable = config.enabledPackages.devenv;
     path = {
@@ -33,6 +62,9 @@ config: pkgs: {
     };
   };
 
+  # devenv: Run devenv commands
+  # Access to full devenv CLI for managing development environments
+  # Only available if config.enabledPackages.devenv = true
   devenv = {
     enable = config.enabledPackages.devenv;
     path = {
@@ -40,6 +72,9 @@ config: pkgs: {
     };
   };
 
+  # updateDeps: Update all project dependencies
+  # Updates: R packages (rixpkgs), Python (uv), Julia (Pkg), flake inputs
+  # Automatically detects which languages are in use
   updateDeps = {
     enable = true;
     path = {
@@ -47,7 +82,9 @@ config: pkgs: {
     };
   };
 
-  node.enable = true;
+  # Additional language runtimes with minimal configuration
-  perl.enable = true;
+  # These are available but not heavily used by this template
-  ruby.enable = true;
+  node.enable = true;  # Node.js runtime (used by some LSPs)
+  perl.enable = true;  # Perl runtime
+  ruby.enable = true;  # Ruby runtime
 }

templates/rde/lib/mini-notify-config.lua

@@ -1,16 +1,42 @@
--- Configuration for mini.notify
+-- Neovim notification configuration using mini.notify
--- Filters out some verbose LSP progress notifications
+--
+-- This file configures the mini.notify plugin to filter out verbose LSP messages.
+-- It reduces noise from the Lua language server during development.
+--
+-- What it does:
+--   - Sets up mini.notify as the notification handler
+--   - Filters out "Diagnosing" and "semantic tokens" messages from lua_ls
+--   - Keeps all other notifications visible
+--
+-- Usage:
+--   Loaded automatically via flake.nix:
+--   optionalLuaPreInit.project = [(builtins.readFile ./lib/mini-notify-config.lua)]
+--
+-- Customization:
+--   - Add more patterns to filter in the predicate function
+--   - Filter notifications from other LSP servers by client_name
+--   - Adjust notification display settings in setup() call
+
+-- Predicate function to filter notifications
+-- Returns true if notification should be shown, false to hide it
 local predicate = function(notif)
+  -- Keep all non-LSP notifications
   if not (notif.data.source == "lsp_progress" and notif.data.client_name == "lua_ls") then
     return true
   end
-  -- Filter out some LSP progress notifications from 'lua_ls'
+  -- Filter out specific verbose LSP progress notifications from lua_ls
+  -- These messages are too frequent and not useful during development
   return notif.msg:find("Diagnosing") == nil and notif.msg:find("semantic tokens") == nil
 end
 
+-- Custom sort function that applies filtering
+-- Filters notification array before sorting
 local custom_sort = function(notif_arr)
   return MiniNotify.default_sort(vim.tbl_filter(predicate, notif_arr))
 end
 
+-- Initialize mini.notify with custom configuration
 require("mini.notify").setup({ content = { sort = custom_sort } })
+
+-- Set mini.notify as the default notification handler
 vim.notify = MiniNotify.make_notify()

templates/rde/lib/shell-hook.nix

@@ -1,8 +1,27 @@
 # Shell hook configuration
+#
+# This module generates the welcome message displayed when entering the dev shell.
+# It provides information about available commands and how to get started.
+#
+# The message includes:
+#   - Project name and welcome banner
+#   - Quick start instructions (initProject, updateDeps)
+#   - List of all available commands based on enabled languages
+#   - Instructions for editing configuration
+#
+# Commands are conditionally shown based on config.enabledLanguages settings.
+# This ensures users only see commands relevant to their configuration.
+#
+# Usage:
+#   Imported in flake.nix as:
+#   shellHook = import ./lib/shell-hook.nix config pkgs;
+#
 # Generates the help message displayed when entering the dev shell
 config: pkgs: let
   inherit (config) defaultPackageName enabledLanguages enabledPackages;
   
+  # Build dynamic list of available commands based on enabled languages
+  # Filters out empty strings for disabled languages
   shellCmds = pkgs.lib.concatLines (pkgs.lib.filter (cmd: cmd != "") [
     (pkgs.lib.optionalString enabledLanguages.r "  - ${defaultPackageName}-r: Launch R console")
     (pkgs.lib.optionalString enabledLanguages.julia "  - ${defaultPackageName}-jl: Launch Julia REPL")

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
+      broom         # Tidy model outputs
-      data_table
+      data_table    # Fast data manipulation
-      janitor
+      janitor       # Data cleaning helpers
-      languageserver
+      languageserver # LSP for IDE support
-      reprex
+      reprex        # Reproducible examples
-      styler
+      styler        # Code formatting
-      tidyverse
+      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;
 }