Add comprehensive inline documentation to all modules and enhance README

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

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;
-  perl.enable = true;
-  ruby.enable = true;
+  # Additional language runtimes with minimal configuration
+  # These are available but not heavily used by this template
+  node.enable = true;  # Node.js runtime (used by some LSPs)
+  perl.enable = true;  # Perl runtime
+  ruby.enable = true;  # Ruby runtime
 }