chore(modules): factor out option doc generation (#152)

* chore(modules): factor out option doc generation

* ci: only validate sources on pushes to main

.github/workflows/ci.yml

@@ -14,9 +14,6 @@ jobs:
     name: Check formatting
     runs-on: ubuntu-latest
 
-    permissions:
-      contents: read
-
     steps:
       - uses: actions/checkout@v4
 
@@ -34,9 +31,6 @@ jobs:
     name: Test Modules
     runs-on: ubuntu-latest
 
-    permissions:
-      contents: read
-
     steps:
       - uses: actions/checkout@v4
 
@@ -48,4 +42,4 @@ jobs:
 
       - name: Run VM
         run: |
-          nix build -L --show-trace ./dev#checks.x86_64-linux.module-vm-test
+          nix build --print-build-logs --show-trace ./dev#checks.x86_64-linux.module-vm-test

.github/workflows/update-docs.yml

@@ -36,7 +36,7 @@ jobs:
       - name: Build & update docs
         run: |
           for module in "nixos" "home-manager"; do
-            nix build -L --show-trace ./dev#"$module"-doc
+            nix build --print-build-logs --show-trace ./dev#"$module"-doc
             cat result > docs/"$module"-options.md
             rm result
           done

.github/workflows/validate-sources.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '_sources/**'
       - 'nvfetcher.toml'
+    branches: [main]
   pull_request:
     paths:
       - '_sources/**'

dev/flake.nix

@@ -10,7 +10,7 @@
     };
   };
 
-  outputs = { self, nixpkgs, ... }@inputs:
+  outputs = { self, nixpkgs, home-manager }:
     let
       systems = [
         "x86_64-linux"
@@ -19,43 +19,28 @@
         "aarch64-darwin"
       ];
 
-      inherit (nixpkgs) lib;
-
-      forAllSystems = fn: lib.genAttrs systems (s: fn nixpkgs.legacyPackages.${s});
+      forAllSystems = fn: nixpkgs.lib.genAttrs systems (system: fn nixpkgs.legacyPackages.${system});
     in
     {
-      checks = forAllSystems (pkgs: lib.optionalAttrs pkgs.stdenv.isLinux {
-        module-vm-test = pkgs.nixosTest (import ../test.nix inputs);
+      checks = forAllSystems ({ lib, pkgs, ... }: lib.optionalAttrs pkgs.stdenv.isLinux {
+        module-vm-test = pkgs.callPackage ../test.nix { inherit home-manager; };
       });
 
       formatter = forAllSystems (pkgs: pkgs.nixpkgs-fmt);
 
       packages = forAllSystems (pkgs:
         let
-          eval = module: lib.evalModules {
-            modules = [
-              module
-              {
-                _module.check = false;
-              }
-            ];
-          };
-
-          mkDoc = name: module:
-            let
-              doc = pkgs.nixosOptionsDoc {
-                options = lib.filterAttrs (n: _: n != "_module") (eval module).options;
-                documentType = "none";
-                revision = builtins.substring 0 8 self.rev or "dirty";
-              };
-            in
-            pkgs.runCommand "${name}-module-doc.md" { } ''
-              cat ${doc.optionsCommonMark} > $out
-            '';
+          version = self.shortRev or self.dirtyShortRev or "unknown";
+          mkOptionDoc = args: (pkgs.callPackage ./option-doc.nix { }) args // { inherit version; };
         in
         {
-          nixos-doc = mkDoc "nixos" ../modules/nixos;
-          home-manager-doc = mkDoc "home-manager" ../modules/home-manager;
+          nixos-doc = mkOptionDoc {
+            modules = [ ../modules/nixos ];
+          };
+
+          home-manager-doc = mkOptionDoc {
+            modules = [ ../modules/home-manager ];
+          };
 
           default = self.packages.${pkgs.system}.home-manager-doc;
         });

dev/option-doc.nix

@@ -0,0 +1,19 @@
+{ lib
+, nixosOptionsDoc
+,
+}: { version
+   , modules
+   ,
+   }:
+let
+  eval = lib.evalModules {
+    modules = modules ++ [{ _module.check = false; }];
+  };
+
+  doc = nixosOptionsDoc {
+    options = lib.filterAttrs (n: _: n != "_module") eval.options;
+    documentType = "none";
+    revision = version;
+  };
+in
+doc.optionsCommonMark

test.nix

@@ -1,21 +1,18 @@
-inputs:
+{ testers, home-manager }:
 let
   common = {
-    catppuccin = {
-      enable = true;
-      flavour = "mocha";
-    };
+    catppuccin.enable = true;
   };
 
-  # shorthand enable
+  # shorthand for enabling a module
   enable = { enable = true; };
 in
-{
+testers.runNixOSTest {
   name = "module-test";
 
   nodes.machine = { lib, ... }: {
     imports = [
-      inputs.home-manager.nixosModules.default
+      home-manager.nixosModules.default
       ./modules/nixos
       common
     ];