chore: add docs & CI

This commit is contained in:
technofab 2025-10-06 17:18:22 +02:00
parent 3363059b65
commit f8f5dbd535
No known key found for this signature in database
18 changed files with 407 additions and 26 deletions

1
.gitignore vendored Normal file
View file

@ -0,0 +1 @@
/result

5
.gitlab-ci.yml Normal file
View file

@ -0,0 +1,5 @@
# Generated by soonix, DO NOT EDIT
include:
- component: gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci@3.0.0-alpha.3
inputs:
version: 3.0.0-alpha.3

8
README.md Normal file
View file

@ -0,0 +1,8 @@
# Rensa Utils
Utilities and helper functions for the rensa ecosystem.
Currently contains functions for finding and importing modules, aswell as
creating/wrapping NixOS+nix-darwin systems and home-manager+disko configs.
See the [docs](https://utils.rensa.projects.tf) for more.

1
docs/images/logo.svg Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" fill="none"><rect width="100" height="100" fill="url(#a)" rx="12"/><path fill="url(#b)" d="M61.56 79.16a13.14 13.14 0 0 0 11.05.32l4.7 8.29-2.7 4.72-5.5.01-7.55-13.34ZM89 67.14l-5.33 9.57-6.94-.02.21-.22a13.06 13.06 0 0 0 3.6-9.33H89ZM58.16 76.7l-10.85-.03-1.3-2.26h9a3 3 0 0 0 .77-.1l2.38 2.39ZM30.51 49.04a29.51 29.51 0 0 0-3.76-.25 3.16 3.16 0 0 0-3.13 3l-.15.23a3.16 3.16 0 0 0 .71 4.09c.63.52 1.46 1.1 2.34 1.67l-3.7 6.5c-2.07 1.01-4.22 2.68-4.91 5.4v.01a3.58 3.58 0 0 0 .3 2.68l-1.75 3.08-5.5-9.46 6.35-11.1-12.62-.02L2 50.14l2.75-4.84 17.96.06 1.5-2.62 6.3 6.3Zm44.2-9.6L69.28 49l-2.88-5.05c.53-.8.75-1.81.53-2.83l-.36-1.68a3.75 3.75 0 0 0-1.27-2.1c.95.49 2.1.48 3.03-.03 1.27.7 2.94.46 3.94-.7.26.01.52 0 .78-.06l1.64 2.9ZM62.83 18.62l6.34-11.06h5.39l2.75 4.83-6.57 11.46H54.97L45.72 7.6l10.83-.1 6.3 11.12Z"/><path fill="url(#c)" d="m54.86 92.4-10.7.1-6.22-11.11-6.27 11.05h-5.31l-2.73-4.82 7.5-13.2h13.6L54.86 92.4Zm-27.4-34.03.78.46c1.45.85 3.1 1.7 4.33 2.14l2.1.74c-1.33.1-2.72.23-4.1.43-1.04.15-2.1.34-3.16.58l-1.19-2.13 1.25-2.22Zm61.7-24.3-6.29 11.08 12.47.03L98 49.9l-2.71 4.83-17.75-.06-1.57 2.77-6.87-6.88L83.7 24.62l5.44 9.45ZM21.43 23.3a13.08 13.08 0 0 0-2.9 9.54H12l5.26-9.56 4.18.02Zm31.75.02.3.54H43.27a3 3 0 0 0-.78.1l-.66-.67 11.37.03Zm-14.06-2.44a13.12 13.12 0 0 0-11.7-1.72l-3.87-6.92 2.66-4.72 5.43-.01 7.48 13.37Z"/><path fill="#fff" d="M74.23 60.65a9.6 9.6 0 0 1-13.58 13.58L24.79 38.37A9.6 9.6 0 0 1 38.37 24.8l35.86 35.86Zm-41.56-30.7a2.3 2.3 0 1 0-3.26 3.27 2.3 2.3 0 0 0 3.26-3.27Zm36.4 36.4a2.3 2.3 0 1 0-3.26 3.26 2.3 2.3 0 0 0 3.26-3.25ZM42.98 64.5h5.1L55 71.4H21.7c-.55 0-1.02-.45-.88-.99C22.4 64.15 39 64.5 42.98 64.5ZM26.8 51.79c2.2-.04 6.65.6 8.56 1.27l2 .71 8.8 8.78-12.59-4.41a34.02 34.02 0 0 1-7.47-4.35c-.16-.13-.03-.34.16-.27l6.68 2.34a.2.2 0 0 0 .26-.12l.36-1.04a.2.2 0 0 0-.12-.25l-6.68-2.35c-.2-.07-.16-.31.04-.31ZM56.48 38.1a.75.75 0 0 1 1.22.42l.4 1.89 1.28-1.46.07-.07a.75.75 0 0 1 1.22.4l.4 1.9 1.28-1.46a.75.75 0 0 1 1.3.34l.36 1.68a.75.75 0 0 1-1.47.31l-.05-.2-1.27 1.45a.75.75 0 0 1-1.3-.34l-.4-1.9-.95 1.1-3.05-3.05.06.01.82-.94.08-.08Zm20.08-11.25c.55 0 .99.45.81.97-.6 1.77-2.56 4.16-4.85 5.76a.2.2 0 0 1-.3-.07l-.36-.74-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.9 1.82a.2.2 0 0 1-.37 0l-.9-1.82-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.91 1.82a.2.2 0 0 1-.36 0l-.91-1.82-.27-.54a.2.2 0 0 0-.36 0l-.26.54-.91 1.82a.2.2 0 0 1-.36 0l-.91-1.82-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.9 1.82a.2.2 0 0 1-.37 0l-.9-1.82-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.91 1.82a.2.2 0 0 1-.36 0l-.91-1.82-.27-.54a.2.2 0 0 0-.36 0l-.26.54-.91 1.82a.2.2 0 0 1-.36 0l-.91-1.82-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.9 1.82a.2.2 0 0 1-.37 0l-.9-1.82-.27-.54a.2.2 0 0 0-.36 0l-.27.54-.1.18-6.1-6.1h33.3Z"/><defs><linearGradient id="b" x1="76.68" x2="59.06" y1="47.7" y2="17.64" gradientUnits="userSpaceOnUse"><stop offset=".24" stop-color="#7EB1DD"/></linearGradient><linearGradient id="c" x1="63.41" x2="81.33" y1="70.75" y2="41.09" gradientUnits="userSpaceOnUse"><stop offset="1" stop-color="#5277C3"/></linearGradient><radialGradient id="a" cx="0" cy="0" r="1" gradientTransform="matrix(0 50 -50 0 50 50)" gradientUnits="userSpaceOnUse"><stop offset=".54" stop-color="#091A3D"/><stop offset="1" stop-color="#000819"/></radialGradient></defs></svg>

After

Width:  |  Height:  |  Size: 3.2 KiB

9
docs/index.md Normal file
View file

@ -0,0 +1,9 @@
# Rensa Utils
Utilities and helper functions for the rensa ecosystem.
Currently contains functions for finding and importing modules, aswell as
creating/wrapping NixOS+nix-darwin systems and home-manager+disko configs.
- [Utility Functions](./utils.md)
- [See all options](./options.md)

3
docs/options.md Normal file
View file

@ -0,0 +1,3 @@
# Options
{% include 'options.md' %}

15
docs/style.css Normal file
View file

@ -0,0 +1,15 @@
.md-header__button.md-logo {
margin: 0;
padding-top: .2rem;
padding-bottom: .2rem;
}
[dir="ltr"] .md-header__title {
margin-left: 0;
}
.md-header__button.md-logo img,
.md-header__button.md-logo svg {
height: 2rem;
}

140
docs/utils.md Normal file
View file

@ -0,0 +1,140 @@
# Utility Functions
## `mkSystem :: attrs -> attrs` { #mkSystem }
Wraps a NixOS or `nix-darwin` configuration. Optionally integrates `nix-wsl` (NixOS only), `disko` (NixOS only) and/or `home-manager`.
**Example**:
```nix title="cells/host/nixos.nix"
{inputs, cell, ...}: let
inherit (inputs) utils;
in {
test = utils.mkSystem {
ren = {
inherit (inputs) pkgs disko;
};
disko.devices = utils.collectDisks cell.disks;
system.stateVersion = "25.11";
};
}
```
**Exposes**:
- `userConfig`: the raw user-passed config
- `innerConfig`: config plus the `ren-module`
- `config`, `options`: nix module config and options passed through
## `mkHome :: attrs -> attrs` { #mkHome }
Wraps a home-manager configuration.
**Example**:
```nix title="cells/host/home.nix"
{inputs, ...}: let
inherit (inputs) utils;
in {
"demo@test" = utils.mkHome {
ren = {
inherit (inputs) pkgs home-manager;
};
home = {
stateVersion = "25.11";
username = "demo";
homeDirectory = "/home/demo";
};
};
}
```
**Exposes**:
- `userConfig`: the raw user-passed config
- `innerConfig`: config plus the `ren-module`
- `activationPackage`: alias for `config.home.activationPackage`
- `config`, `options`: nix module config and options passed through
## `mkDisk :: attrs -> attrs` { #mkDisk }
Wraps a single disko configuration. Exposes the disk's generated scripts etc.
**Example**:
```nix title="cells/host/disks/some_disk.nix"
{inputs, ...}: let
inherit (inputs) utils;
in utils.mkDisk {
ren = {
inherit (inputs) pkgs disko;
};
disk."whatever" = {
device = "/device";
type = "disk";
content = {
type = "gpt";
partitions = {
boot = {
size = "1M";
type = "EF02";
attributes = [0];
};
root = {
size = "100%";
content = {
type = "filesystem";
format = "ext4";
mountpoint = "/";
};
};
};
};
};
}
```
**Exposes**:
- `userConfig`: the raw user-passed config
- `innerConfig`: config without `ren` config attributes
- `scripts`: the disks scripts, for mounting, formatting etc.
- `config`, `options`: nix module config and options passed through
## `collectDisks :: attrs -> attrs` { #collectDisks }
Collects all disks from the cell, can be passed to `#!nix disko.devices`.
**Example**:
```nix
disko.devices = utils.collectDisks cell.disks;
```
**Arguments**:
- `disks`: all disks from the current cell for example
## `findModules :: {dir, currentFile, relative} -> [files]` { #findModules }
Find modules/files in directory, return them all as a list of paths to import.
**Arguments**
- `dir`: directory to search in
- `currentFile`: file to exclude (default: `#!nix "default.nix"`)
- `relative`: whether to return relative paths (default: `#!nix false`)
## `importModules :: {dir, args, currentFile, usePathAsKeys} -> attrs` { #importModules }
Find, then import, then merge all modules in a dir.
**Arguments**
- `dir`: directory to search in
- `args`: arguments to pass to the imported modules (default: `#!nix {}`)
- `currentFile`: file to exclude (default: `#!nix "default.nix"`)
- `usePathAsKeys`: whether to nest the values by their path (default: `#!nix false`)

View file

@ -4,7 +4,11 @@
ren.url = "gitlab:rensa-nix/core?dir=lib";
};
outputs = {ren, ...} @ inputs:
outputs = {
ren,
self,
...
} @ inputs:
ren.buildWith
{
inherit inputs;
@ -16,7 +20,14 @@
};
cellBlocks = with ren.blocks; [
(simple "devShells")
(simple "docs")
(simple "ci")
];
}
{};
{
packages = ren.select self [
["repo" "docs"]
["repo" "ci" "packages"]
];
};
}

View file

@ -13,6 +13,8 @@
recursiveUpdate
;
in rec {
module = ./ren-module.nix;
mkSystem = import ./mkSystem.nix args;
mkHome = import ./mkHome.nix args;
mkDisk = import ./mkDisk.nix args;

View file

@ -26,7 +26,7 @@
};
imports =
# add home-manager if the input is passed
optionals (evaled.options.ren.home-manager.isDefined) [
optionals evaled.options.ren.home-manager.isDefined [
evaled.config.ren.home-manager.nixosModules.home-manager
{
home-manager.useGlobalPkgs = mkDefault true;
@ -34,20 +34,20 @@
}
]
# add nixos-wsl if the input is passed
++ optionals (evaled.options.ren.nixos-wsl.isDefined) [
++ optionals evaled.options.ren.nixos-wsl.isDefined [
evaled.config.ren.nixos-wsl.nixosModules.wsl
{
wsl.enable = mkDefault true;
}
]
# add disko if the input is passed
++ optionals (evaled.options.ren.disko.isDefined) [
++ optionals evaled.options.ren.disko.isDefined [
evaled.config.ren.disko.nixosModules.disko
];
};
extraDarwinConfig = {
# add home-manager if the input is passed
imports = optionals (evaled.options.ren.home-manager.isDefined) [
imports = optionals evaled.options.ren.home-manager.isDefined [
evaled.config.ren.home-manager.darwinModules.home-manager
{
home-manager.useGlobalPkgs = mkDefault true;

View file

@ -1,37 +1,42 @@
{
config,
lib,
config,
options,
...
}: let
inherit (lib) mkOption mkOptionType types isAttrs hasAttr;
mkInputOption = description:
inherit (lib) mkOption mkOptionType types isAttrs hasAttr literalExpression;
mkInputOption = name: description:
mkOption {
type = mkOptionType {
name = "input";
description = "a flake input";
description = "flake input for ${name}";
check = x: (isAttrs x) && (hasAttr "sourceInfo" x);
};
description = ''
The flake input for ${description}.
Example:
ren.home-manager = inputs.home-manager;
'';
example = literalExpression "inputs.${name}";
};
in {
options.ren = {
system = mkOption {
type = types.str;
description = ''
The system architecture (e.g., 'x86_64-linux', 'aarch64-darwin').
The system architecture (e.g., `x86_64-linux`, `aarch64-darwin`).
'';
default =
if options.ren.pkgs.isDefined
then config.ren.pkgs.system
else "";
defaultText = literalExpression ''
if options.ren.pkgs.isDefined then config.ren.pkgs.system else "";
'';
default = config.ren.pkgs.system or "";
};
home-manager = mkInputOption "Home Manager";
disko = mkInputOption "Disko";
nixos-wsl = mkInputOption "NixOS-WSL";
nix-darwin = mkInputOption "nix-darwin";
home-manager = mkInputOption "home-manager" "Home Manager";
disko = mkInputOption "disko" "Disko";
nixos-wsl = mkInputOption "nixos-wsl" "NixOS-WSL";
nix-darwin = mkInputOption "nix-darwin" "nix-darwin";
pkgs = mkOption {
type = mkOptionType {
@ -42,6 +47,9 @@ in {
description = ''
An instantiated nixpkgs set. Used for general pkgs and to get NixOS systems' modules.
'';
example = literalExpression ''
import inputs.nixpkgs { system = "aarch64-linux"; };
'';
};
};
}

34
nix/repo/ci.nix Normal file
View file

@ -0,0 +1,34 @@
{inputs, ...}: let
inherit (inputs) cilib;
in
cilib.mkCI {
pipelines."default" = {
stages = ["build" "deploy"];
jobs = {
"docs" = {
stage = "build";
script = [
# sh
''
nix build .#docs:default
mkdir -p public
cp -r result/. public/
''
];
artifacts.paths = ["public"];
};
"pages" = {
nix.enable = false;
image = "alpine:latest";
stage = "deploy";
script = ["true"];
artifacts.paths = ["public"];
rules = [
{
"if" = "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
}
];
};
};
};
}

View file

@ -1,16 +1,24 @@
{inputs, ...}: let
inherit (inputs) pkgs devshell treefmt;
{
inputs,
cell,
...
}: let
inherit (inputs) pkgs devshell treefmt soonix;
inherit (cell) ci;
in {
default = devshell.mkShell {
imports = [soonix.devshellModule];
packages = [
pkgs.nil
(treefmt.mkWrapper pkgs {
programs = {
alejandra.enable = true;
statix.enable = true;
deadnix.enable = true;
mdformat.enable = true;
};
})
];
soonix.hooks.ci = ci.soonix;
};
}

74
nix/repo/docs.nix Normal file
View file

@ -0,0 +1,74 @@
{inputs, ...}: let
inherit (inputs) pkgs utils doclib;
optionsDoc = doclib.mkOptionDocs {
inherit (utils) module;
roots = [
{
url = "https://gitlab.com/rensa-nix/utils/-/blob/main/lib";
path = "${inputs.self}/lib";
}
];
};
optionsDocs = pkgs.runCommand "options-docs" {} ''
mkdir -p $out
ln -s ${optionsDoc} $out/options.md
'';
in
(doclib.mkDocs {
docs."default" = {
base = "${inputs.self}";
path = "${inputs.self}/docs";
material = {
enable = true;
colors = {
primary = "red";
accent = "red";
};
umami = {
enable = true;
src = "https://analytics.tf/umami";
siteId = "1e063417-931a-4fb7-81a1-fc506372ebcc";
domains = ["utils.rensa.projects.tf"];
};
};
macros = {
enable = true;
includeDir = toString optionsDocs;
};
config = {
site_name = "Utils";
site_url = "https://utils.rensa.projects.tf";
repo_name = "rensa-nix/utils";
repo_url = "https://gitlab.com/rensa-nix/utils";
extra_css = ["style.css"];
theme = {
logo = "images/logo.svg";
icon.repo = "simple/gitlab";
favicon = "images/logo.svg";
};
nav = [
{"Introduction" = "index.md";}
{"Utility Functions" = "utils.md";}
{"Options" = "options.md";}
];
markdown_extensions = [
{
"pymdownx.highlight".pygments_lang_class = true;
}
"pymdownx.inlinehilite"
"pymdownx.snippets"
"pymdownx.superfences"
"pymdownx.escapeall"
"fenced_code"
"attr_list"
{
"toc".permalink = "#";
}
];
};
};
}).packages
// {
inherit optionsDocs;
}

59
nix/repo/flake.lock generated
View file

@ -1,6 +1,6 @@
{
"nodes": {
"devshell-lib": {
"devshell": {
"locked": {
"dir": "lib",
"lastModified": 1758204313,
@ -17,12 +17,67 @@
"type": "gitlab"
}
},
"nix-gitlab-ci-lib": {
"locked": {
"dir": "lib",
"lastModified": 1758804624,
"narHash": "sha256-2AdxBYJKflgO7oZr1CfzyAxivDkGjvFmQpOuN6Yq128=",
"owner": "TECHNOFAB",
"repo": "nix-gitlab-ci",
"rev": "d88ada2c41ae05b08d7ec644a4d222e93fff78ae",
"type": "gitlab"
},
"original": {
"dir": "lib",
"owner": "TECHNOFAB",
"ref": "3.0.0-alpha.3",
"repo": "nix-gitlab-ci",
"type": "gitlab"
}
},
"nixmkdocs": {
"locked": {
"dir": "lib",
"lastModified": 1757055638,
"narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=",
"owner": "TECHNOFAB",
"repo": "nixmkdocs",
"rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74",
"type": "gitlab"
},
"original": {
"dir": "lib",
"owner": "TECHNOFAB",
"repo": "nixmkdocs",
"type": "gitlab"
}
},
"root": {
"inputs": {
"devshell-lib": "devshell-lib",
"devshell": "devshell",
"nix-gitlab-ci-lib": "nix-gitlab-ci-lib",
"nixmkdocs": "nixmkdocs",
"soonix-lib": "soonix-lib",
"treefmt-nix": "treefmt-nix"
}
},
"soonix-lib": {
"locked": {
"dir": "lib",
"lastModified": 1758615778,
"narHash": "sha256-tggru+siXlLcLUjHtMojkJJWTS/8I3gm8nhnlz+qrTo=",
"owner": "TECHNOFAB",
"repo": "soonix",
"rev": "e04b71c07413251dcb52036b4a51c6c7c0dca2ad",
"type": "gitlab"
},
"original": {
"dir": "lib",
"owner": "TECHNOFAB",
"repo": "soonix",
"type": "gitlab"
}
},
"treefmt-nix": {
"flake": false,
"locked": {

View file

@ -1,6 +1,9 @@
{
inputs = {
devshell-lib.url = "gitlab:rensa-nix/devshell?dir=lib";
nixmkdocs.url = "gitlab:TECHNOFAB/nixmkdocs?dir=lib";
devshell.url = "gitlab:rensa-nix/devshell?dir=lib";
soonix-lib.url = "gitlab:TECHNOFAB/soonix?dir=lib";
nix-gitlab-ci-lib.url = "gitlab:TECHNOFAB/nix-gitlab-ci/3.0.0-alpha.3?dir=lib";
treefmt-nix = {
url = "github:numtide/treefmt-nix";
flake = false;
@ -9,7 +12,11 @@
outputs = i:
i
// {
devshell = i.devshell-lib.lib {inherit (i.parent) pkgs;};
doclib = i.nixmkdocs.lib {inherit (i.parent) pkgs;};
devshell = i.devshell.lib {inherit (i.parent) pkgs;};
soonix = i.soonix-lib.lib {inherit (i.parent) pkgs;};
cilib = i.nix-gitlab-ci-lib.lib {inherit (i.parent) pkgs;};
utils = import "${i.parent.self}/lib" {inherit (i.parent.pkgs) lib;};
treefmt = import i.treefmt-nix;
};
}

View file

@ -7,7 +7,7 @@
nix-darwin.url = "github:lnl7/nix-darwin";
};
outputs = {...} @ inputs: let
outputs = inputs: let
lib = import ../lib {inherit (inputs.nixpkgs) lib;};
pkgs = inputs.nixpkgs.legacyPackages.aarch64-linux;
in rec {