mirror of
https://github.com/dwinkler1/np.git
synced 2026-02-19 14:30:59 -05:00
Add comprehensive inline documentation to all modules and enhance README
Co-authored-by: dwinkler1 <22460147+dwinkler1@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
c19248f706
commit
40095ac868
13 changed files with 587 additions and 32 deletions
|
|
@ -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
|
||||
- `enabledLanguages`: Enable/disable R, Python, Julia support
|
||||
- `enabledPackages`: Enable additional features like devenv
|
||||
- `theme`: Configure Neovim color scheme
|
||||
**System-wide** (edit `overlays/r.nix`):
|
||||
```nix
|
||||
reqPkgs = with final.rpkgs.rPackages; [
|
||||
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/`
|
||||
- **New commands**: Add host configs in `hosts/`
|
||||
- **New scripts**: Add shell scripts in `scripts/`
|
||||
- **New languages**: Create new host and overlay files
|
||||
- **Modify shell welcome**: Edit `lib/shell-hook.nix`
|
||||
```bash
|
||||
uv add package-name
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue