From f8f5dbd5350272aa1065ffd82b247caaa88609e9 Mon Sep 17 00:00:00 2001 From: technofab Date: Mon, 6 Oct 2025 17:18:22 +0200 Subject: [PATCH] chore: add docs & CI --- .gitignore | 1 + .gitlab-ci.yml | 5 ++ README.md | 8 +++ docs/images/logo.svg | 1 + docs/index.md | 9 +++ docs/options.md | 3 + docs/style.css | 15 +++++ docs/utils.md | 140 +++++++++++++++++++++++++++++++++++++++++ flake.nix | 15 ++++- lib/default.nix | 2 + lib/mkSystem.nix | 8 +-- lib/ren-module.nix | 34 ++++++---- nix/repo/ci.nix | 34 ++++++++++ nix/repo/devShells.nix | 12 +++- nix/repo/docs.nix | 74 ++++++++++++++++++++++ nix/repo/flake.lock | 59 ++++++++++++++++- nix/repo/flake.nix | 11 +++- test/flake.nix | 2 +- 18 files changed, 407 insertions(+), 26 deletions(-) create mode 100644 .gitignore create mode 100644 .gitlab-ci.yml create mode 100644 README.md create mode 100644 docs/images/logo.svg create mode 100644 docs/index.md create mode 100644 docs/options.md create mode 100644 docs/style.css create mode 100644 docs/utils.md create mode 100644 nix/repo/ci.nix create mode 100644 nix/repo/docs.nix diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c4a847d --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/result diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..1af5ed2 --- /dev/null +++ b/.gitlab-ci.yml @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..449fb63 --- /dev/null +++ b/README.md @@ -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. diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..d5b927e --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a1661cc --- /dev/null +++ b/docs/index.md @@ -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) diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..4ca74a4 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,3 @@ +# Options + +{% include 'options.md' %} diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..b2ae4ff --- /dev/null +++ b/docs/style.css @@ -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; +} + diff --git a/docs/utils.md b/docs/utils.md new file mode 100644 index 0000000..bff0981 --- /dev/null +++ b/docs/utils.md @@ -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`) diff --git a/flake.nix b/flake.nix index 76be494..21a37d8 100644 --- a/flake.nix +++ b/flake.nix @@ -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"] + ]; + }; } diff --git a/lib/default.nix b/lib/default.nix index 2f48264..680d68e 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -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; diff --git a/lib/mkSystem.nix b/lib/mkSystem.nix index f0f06d1..2ebf128 100644 --- a/lib/mkSystem.nix +++ b/lib/mkSystem.nix @@ -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; diff --git a/lib/ren-module.nix b/lib/ren-module.nix index 9247be4..0630af4 100644 --- a/lib/ren-module.nix +++ b/lib/ren-module.nix @@ -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"; }; + ''; }; }; } diff --git a/nix/repo/ci.nix b/nix/repo/ci.nix new file mode 100644 index 0000000..b0798f3 --- /dev/null +++ b/nix/repo/ci.nix @@ -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"; + } + ]; + }; + }; + }; + } diff --git a/nix/repo/devShells.nix b/nix/repo/devShells.nix index 2eb5c90..3dc1778 100644 --- a/nix/repo/devShells.nix +++ b/nix/repo/devShells.nix @@ -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; }; } diff --git a/nix/repo/docs.nix b/nix/repo/docs.nix new file mode 100644 index 0000000..4d3141d --- /dev/null +++ b/nix/repo/docs.nix @@ -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; + } diff --git a/nix/repo/flake.lock b/nix/repo/flake.lock index a29e62e..4816254 100644 --- a/nix/repo/flake.lock +++ b/nix/repo/flake.lock @@ -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": { diff --git a/nix/repo/flake.nix b/nix/repo/flake.nix index db3b784..6b88fd1 100644 --- a/nix/repo/flake.nix +++ b/nix/repo/flake.nix @@ -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; }; } diff --git a/test/flake.nix b/test/flake.nix index c3aeb56..9e966d2 100644 --- a/test/flake.nix +++ b/test/flake.nix @@ -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 {