mirror of
https://github.com/dwinkler1/np.git
synced 2026-02-19 22:40:57 -05:00
Update README with ED template documentation
Co-authored-by: dwinkler1 <22460147+dwinkler1@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
0e20fe6229
commit
5ac0c775ef
2 changed files with 361 additions and 3 deletions
80
README.md
80
README.md
|
|
@ -4,9 +4,32 @@ A collection of Nix flake templates for reproducible development environments.
|
|||
|
||||
## Templates
|
||||
|
||||
### ED (Editor)
|
||||
|
||||
A simple Neovim-based development environment with optional language support.
|
||||
|
||||
**Quick start:**
|
||||
```bash
|
||||
nix flake init -t github:dwinkler1/np#ed
|
||||
nix develop
|
||||
vv # Launch Neovim (custom binary name)
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- ✨ Lightweight Neovim configuration
|
||||
- 🔧 Configurable language support (Python, R, Julia, Nix)
|
||||
- 📦 Reproducible with Nix
|
||||
- 🎨 Custom theming (Kanagawa by default)
|
||||
- 🔔 Mini-notify plugin for notifications
|
||||
|
||||
**Default configuration:**
|
||||
- Nix support enabled
|
||||
- Custom binary: `vv`
|
||||
- Includes: cowsay, updateR utility
|
||||
|
||||
### RDE (Research Development Environment)
|
||||
|
||||
The default template for data science and research projects with support for R, Python, and Julia.
|
||||
A comprehensive template for data science and research projects with support for R, Python, and Julia.
|
||||
|
||||
**Quick start:**
|
||||
```bash
|
||||
|
|
@ -34,12 +57,63 @@ All templates are automatically tested to ensure functionality:
|
|||
|
||||
### CI Workflows
|
||||
|
||||
- `.github/workflows/check.yml` - Comprehensive functionality tests (Ubuntu)
|
||||
- `.github/workflows/check_macos.yml` - macOS compatibility tests
|
||||
**RDE Template:**
|
||||
- `.github/workflows/check.yml` - Comprehensive functionality tests for RDE (Ubuntu)
|
||||
- Basic build and flake checks
|
||||
- Dev shell functionality
|
||||
- R command availability and functionality
|
||||
- Neovim integration
|
||||
- Utility commands (p-initProject, p-updateDeps)
|
||||
- Separate jobs for Python and Julia configurations
|
||||
|
||||
**ED Template:**
|
||||
- `.github/workflows/check_ed.yml` - Comprehensive functionality tests for ED (Ubuntu)
|
||||
- Basic build and flake checks
|
||||
- Dev shell functionality
|
||||
- Neovim (vv) command tests
|
||||
- updateR utility tests
|
||||
- Extra packages (cowsay) verification
|
||||
- Separate jobs for Python, R, Julia, and multi-language configurations
|
||||
|
||||
**Cross-platform:**
|
||||
- `.github/workflows/check_macos.yml` - macOS compatibility tests for both templates
|
||||
- `.github/workflows/update.yml` - Automated dependency updates
|
||||
|
||||
## Usage
|
||||
|
||||
### ED Template
|
||||
|
||||
1. **Initialize a new project:**
|
||||
```bash
|
||||
nix flake init -t github:dwinkler1/np#ed
|
||||
```
|
||||
|
||||
2. **Enter development environment:**
|
||||
```bash
|
||||
nix develop
|
||||
# or with direnv
|
||||
echo "use flake" > .envrc && direnv allow
|
||||
```
|
||||
|
||||
3. **Start editing:**
|
||||
```bash
|
||||
vv # Launch Neovim
|
||||
updateR # Update R packages (when R is enabled)
|
||||
cowsay "Hello!" # Fun utility included
|
||||
```
|
||||
|
||||
4. **Enable languages:**
|
||||
Edit `flake.nix` and change `false` to `true` in the `cats` section:
|
||||
```nix
|
||||
cats = {
|
||||
python = true; # Enable Python support
|
||||
r = true; # Enable R support
|
||||
julia = true; # Enable Julia support
|
||||
};
|
||||
```
|
||||
|
||||
### RDE Template
|
||||
|
||||
1. **Initialize a new project:**
|
||||
```bash
|
||||
nix flake init -t github:dwinkler1/np#rde
|
||||
|
|
|
|||
284
templates/ed/README.md
Normal file
284
templates/ed/README.md
Normal file
|
|
@ -0,0 +1,284 @@
|
|||
# ED Template - Simple Editor Environment
|
||||
|
||||
A lightweight, customizable Neovim-based development environment with optional language support for Python, R, Julia, and Nix.
|
||||
|
||||
## Features
|
||||
|
||||
- ✨ **Lightweight**: Minimal configuration, fast startup
|
||||
- 🔧 **Configurable**: Enable only the languages you need
|
||||
- 📦 **Reproducible**: Nix-based environment management
|
||||
- 🎨 **Themed**: Beautiful Kanagawa colorscheme (customizable)
|
||||
- 🔔 **Notifications**: Mini-notify plugin for user feedback
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize a new project with the ED template
|
||||
nix flake init -t github:dwinkler1/np#ed
|
||||
|
||||
# Enter the development environment
|
||||
nix develop
|
||||
|
||||
# Launch Neovim
|
||||
vv
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The ED template uses a centralized configuration structure at the top of `flake.nix`:
|
||||
|
||||
```nix
|
||||
cats = {
|
||||
clickhouse = false;
|
||||
gitPlugins = false;
|
||||
julia = false;
|
||||
lua = false;
|
||||
markdown = false;
|
||||
nix = true; # Enabled by default
|
||||
optional = false;
|
||||
python = false;
|
||||
r = false;
|
||||
};
|
||||
```
|
||||
|
||||
### Enabling Languages
|
||||
|
||||
To enable support for a specific language, edit `flake.nix` and set the corresponding cat to `true`:
|
||||
|
||||
#### Python
|
||||
```nix
|
||||
cats = {
|
||||
python = true;
|
||||
# ... other settings
|
||||
};
|
||||
```
|
||||
|
||||
Includes: Python 3, duckdb, polars packages by default
|
||||
|
||||
#### R
|
||||
```nix
|
||||
cats = {
|
||||
r = true;
|
||||
# ... other settings
|
||||
};
|
||||
```
|
||||
|
||||
Includes: fixest package by default
|
||||
|
||||
#### Julia
|
||||
```nix
|
||||
cats = {
|
||||
julia = true;
|
||||
# ... other settings
|
||||
};
|
||||
```
|
||||
|
||||
Includes: StatsBase package by default
|
||||
|
||||
### Custom Package Files
|
||||
|
||||
You can specify additional packages by creating these files in your project:
|
||||
|
||||
- `python-packages.nix` - Additional Python packages
|
||||
```nix
|
||||
p: with p; [
|
||||
numpy
|
||||
pandas
|
||||
# ... more packages
|
||||
]
|
||||
```
|
||||
|
||||
- `r-packages.nix` - Additional R packages
|
||||
```nix
|
||||
p: with p.rPackages; [
|
||||
ggplot2
|
||||
dplyr
|
||||
# ... more packages
|
||||
]
|
||||
```
|
||||
|
||||
- `julia-packages.nix` - Additional Julia packages
|
||||
```nix
|
||||
[
|
||||
"DataFrames"
|
||||
"Plots"
|
||||
# ... more packages
|
||||
]
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Neovim
|
||||
- `vv` - Launch Neovim (custom binary name)
|
||||
- `vv --headless` - Run Neovim in headless mode for scripting
|
||||
|
||||
### Utilities
|
||||
- `updateR` - Update R package snapshots from rstats-on-nix
|
||||
- `cowsay` - Fun ASCII art text formatter (included as example)
|
||||
|
||||
## Customization
|
||||
|
||||
### Binary Name
|
||||
|
||||
The default binary name is `vv`. To change it, edit the `binName` in `flake.nix`:
|
||||
|
||||
```nix
|
||||
binName = "myeditor"; # Changes command from 'vv' to 'myeditor'
|
||||
```
|
||||
|
||||
### Colorscheme
|
||||
|
||||
Change the colorscheme in the settings section:
|
||||
|
||||
```nix
|
||||
settings = {
|
||||
colorscheme = "kanagawa"; # or "gruvbox", "tokyonight", etc.
|
||||
background = "dark"; # or "light"
|
||||
# ...
|
||||
};
|
||||
```
|
||||
|
||||
### Extra Packages
|
||||
|
||||
Add more system packages in the `extraPackages` section:
|
||||
|
||||
```nix
|
||||
extraPackages = with pkgs; [
|
||||
cowsay
|
||||
ripgrep
|
||||
fd
|
||||
# ... more packages
|
||||
];
|
||||
```
|
||||
|
||||
### Welcome Message
|
||||
|
||||
The template includes a welcome notification. Customize it in the `specs.extraLua` section:
|
||||
|
||||
```nix
|
||||
config = ''
|
||||
require("mini.notify").setup()
|
||||
vim.notify = MiniNotify.make_notify()
|
||||
vim.notify("Welcome to ${name}!")
|
||||
'';
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The template sets the following environment variables:
|
||||
|
||||
- `IS_PROJECT_EDITOR=1` - Indicates you're in the project editor environment
|
||||
- `R_LIBS_USER=./.nvimcom` - Project-local R package directory
|
||||
|
||||
## Language Package Management
|
||||
|
||||
### Replace vs Merge
|
||||
|
||||
By default, language packages are **replaced** rather than merged with base packages. This is controlled by:
|
||||
|
||||
```nix
|
||||
let
|
||||
replace = pkgs.lib.mkForce;
|
||||
in {
|
||||
lang_packages = {
|
||||
python = replace ([...]); # Replaces base packages
|
||||
r = replace ([...]); # Replaces base packages
|
||||
julia = replace ([...]); # Replaces base packages
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
To **merge** with base packages instead, remove the `replace` wrapper:
|
||||
|
||||
```nix
|
||||
lang_packages = {
|
||||
python = (with pkgs.python3Packages; [...]);
|
||||
# ...
|
||||
};
|
||||
```
|
||||
|
||||
## Development Shell
|
||||
|
||||
The development shell provides access to the Neovim package plus additional utilities:
|
||||
|
||||
```bash
|
||||
nix develop # Enter the dev shell
|
||||
```
|
||||
|
||||
Available in dev shell:
|
||||
- `vv` - The configured Neovim
|
||||
- `updateR` - Update R packages (when R support is enabled)
|
||||
- All packages listed in `extraPackages`
|
||||
|
||||
## Testing
|
||||
|
||||
The ED template has comprehensive CI/CD tests:
|
||||
|
||||
### Automated Tests (`.github/workflows/check_ed.yml`)
|
||||
|
||||
1. **Basic Tests** (Ubuntu)
|
||||
- Build verification
|
||||
- Flake check
|
||||
- Dev shell entry
|
||||
- Neovim launch and version check
|
||||
- Utility commands availability
|
||||
|
||||
2. **Language-Specific Tests**
|
||||
- Python configuration: Package imports, code execution
|
||||
- R configuration: Package loading, code execution
|
||||
- Julia configuration: Version check, code execution
|
||||
- Multi-language: All languages enabled together
|
||||
|
||||
3. **macOS Tests** (`.github/workflows/check_macos.yml`)
|
||||
- Build verification on macOS
|
||||
- Basic functionality tests
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Use direnv for automatic environment loading:**
|
||||
```bash
|
||||
echo "use flake" > .envrc
|
||||
direnv allow
|
||||
```
|
||||
|
||||
2. **Pin specific package versions** by editing `flake.lock`:
|
||||
```bash
|
||||
nix flake update # Update all inputs
|
||||
nix flake lock --update-input nixpkgs # Update specific input
|
||||
```
|
||||
|
||||
3. **Check what's included in your build:**
|
||||
```bash
|
||||
nix path-info -Sh ./result
|
||||
```
|
||||
|
||||
4. **Build for different platforms:**
|
||||
```bash
|
||||
nix build .#packages.x86_64-linux.default
|
||||
nix build .#packages.aarch64-darwin.default
|
||||
```
|
||||
|
||||
## Comparison with RDE Template
|
||||
|
||||
| Feature | ED Template | RDE Template |
|
||||
|---------|-------------|--------------|
|
||||
| **Complexity** | Lightweight | Comprehensive |
|
||||
| **Binary Name** | `vv` | `p` |
|
||||
| **Project Structure** | Manual | `p-initProject` command |
|
||||
| **Language Support** | Optional (Python, R, Julia, Nix) | Built-in (R default, Python/Julia optional) |
|
||||
| **Research Tools** | None | Quarto, Marimo, Pluto.jl |
|
||||
| **Package Management** | updateR | p-updateDeps (comprehensive) |
|
||||
| **Use Case** | Simple editing, lightweight projects | Research, data science, complex projects |
|
||||
|
||||
## Contributing
|
||||
|
||||
When modifying the ED template, please ensure:
|
||||
|
||||
1. All tests pass in `.github/workflows/check_ed.yml`
|
||||
2. The template builds on both Linux and macOS
|
||||
3. Documentation is updated to reflect changes
|
||||
4. Changes follow the existing code patterns
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](../../LICENSE) file for details.
|
||||
Loading…
Add table
Add a link
Reference in a new issue