docs: add generated modules readme

_outputs.nix

@@ -127,7 +127,7 @@
 
     homeManagerModules = import ./homeManagerModules self;
 
-    nixosModules = import ./modules self;
+    nixosModules = import ./modules {inherit self;};
 
     overlays = import ./overlays self;
 

apps/gen-docs/getModuleMeta.nix

@@ -0,0 +1,13 @@
+attr: selfPath: let
+  inherit (builtins) mapAttrs replaceStrings;
+
+  modules = import "${selfPath}/${attr}" {description = true;};
+
+  trimNewlines = s: replaceStrings ["\n"] [" "] s;
+in {
+  attrs =
+    mapAttrs (_: v: {
+      desc = trimNewlines v;
+    })
+    modules;
+}

apps/gen-docs/script.sh

@@ -9,8 +9,20 @@ substitute() {
     ) -t markdown --template "$FLAKE/apps/gen-docs/templates/$2.md" -o "$FLAKE/$2/README.md"
 }
 
+substituteModule() {
+    echo '' | pandoc --metadata-file <(
+        nix eval \
+            --impure \
+            --json \
+            --expr "\"$FLAKE\"" \
+            --apply "(import \"$FLAKE/apps/gen-docs/getModuleMeta.nix\") \"$1\"" |
+            jq -r
+    ) -t markdown --template "$FLAKE/apps/gen-docs/templates/$1.md" -o "$FLAKE/$1/README.md"
+}
+
 # TODO: add homeManagerModules, lib, modules, nixFastChecks, overlays, scopedPackages
 substitute "appsPackages" "apps" "getPackageMeta"
 substitute "nixosConfigurations" "configurations" "getConfigMeta"
 substitute "devShells" "devShells" "getPackageMeta"
 substitute "packages" "packages" "getPackageMeta"
+substituteModule "modules"

apps/gen-docs/templates/modules.md

@@ -0,0 +1,11 @@
+# nixosModules
+
+This directory contains every modules for NixOS exposed by this flake.
+
+## List of my modules found in `self.nixosModules`
+
+| Name | Description |
+| ---- | ----------- |
+$for(attrs/pairs)$
+| `$it.key$` | $it.value.desc/nowrap$ |
+$endfor$

modules/README.md

@@ -0,0 +1,23 @@
+# nixosModules
+
+This directory contains every modules for NixOS exposed by this flake.
+
+## List of my modules found in `self.nixosModules`
+
+| Name | Description |
+| ---- | ----------- |
+| `base` | Sets up locale, nix config, binary caches, general packages and some miscellaneous configs I might want on every device I use. |
+| `base-droid` | Sets up locale, nix config, binary caches, general packages and some miscellaneous configs I might want on every nix-on-droid device I use. |
+| `borgbackup` | Sets up a wrapper around `services.borgbackup` to setup default behaviour and make configuration of backups easier. |
+| `caddy-plus` | Extends the caddy options to allow declaring subdirectory routes and reverse proxy directives through nix code. |
+| `desktop` | Sets up a Display Manager, a Desktop Environment and themes for any graphical apps to use the Dracula Theme. This module uses Hyprland as window manager and AGS / Astal for the UI. |
+| `docker` | Imports my [Khepri fork](https://github.com/matt1432/khepri), sets default options such as BTRFS filesystem and adds an update script for images. |
+| `esphome-plus` | Fixes a bug with compilation of m5-atom-stack firmware and allows declaring firmware configurations in nix code. |
+| `ha-plus` | Extends the home-assistant options to allow declaring the content of specific configuration files in the home-assistant configuration directory such as custom sentences through nix code. |
+| `kmscon` | Extends the kmscon options to add more descriptive ones. |
+| `meta` | Adds options to declare the documentation of my devices that will be generated to `./configurations/README.md`. |
+| `nvidia` | Abstracts NVIDIA options and miscellaneous fixes behind simpler options. |
+| `plymouth` | Sets some boot options to make the boot sequence cleaner. |
+| `server` | Sets up sshd, tailscale and related configurations. |
+| `tmux` | Uses the home-manager tmux module to declare my custom configuration and links it to `/etc` to set it globally. |
+| `wyoming-plus` | Extends the `wyoming.openwakeword` options to allow declaring flags used by the [fork](https://github.com/rhasspy/wyoming-openwakeword/pull/17) of `wyoming-openwakeword` exposed by this module. |

modules/default.nix

@@ -1,17 +1,128 @@
-self: {
-  base = import ./base self;
-  base-droid = import ./base/default-droid.nix self;
-  borgbackup = import ./borgbackup;
-  caddy-plus = import ./caddy-plus self;
-  desktop = import ./desktop self;
-  docker = import ./docker self.inputs.khepri;
-  esphome-plus = import ./esphome-plus;
-  ha-plus = import ./ha-plus;
-  kmscon = import ./kmscon;
-  nvidia = import ./nvidia;
-  meta = import ./meta;
-  plymouth = import ./plymouth;
-  server = import ./server;
-  tmux = import ./tmux;
-  wyoming-plus = import ./wyoming-plus;
+{
+  self ? {},
+  description ? false,
+}: let
+  module = mod: desc:
+    if description
+    then desc
+    else mod;
+in {
+  base =
+    module
+    (import ./base self)
+    ''
+      Sets up locale, nix config, binary caches, general packages and some
+      miscellaneous configs I might want on every device I use.
+    '';
+
+  base-droid =
+    module
+    (import ./base/default-droid.nix self)
+    ''
+      Sets up locale, nix config, binary caches, general packages and some
+      miscellaneous configs I might want on every nix-on-droid device I use.
+    '';
+
+  borgbackup =
+    module
+    (import ./borgbackup)
+    ''
+      Sets up a wrapper around `services.borgbackup` to setup default behaviour
+      and make configuration of backups easier.
+    '';
+
+  caddy-plus =
+    module
+    (import ./caddy-plus self)
+    ''
+      Extends the caddy options to allow declaring subdirectory routes and
+      reverse proxy directives through nix code.
+    '';
+
+  desktop =
+    module
+    (import ./desktop self)
+    ''
+      Sets up a Display Manager, a Desktop Environment and themes for any graphical
+      apps to use the Dracula Theme. This module uses Hyprland as window manager and
+      AGS / Astal for the UI.
+    '';
+
+  docker =
+    module
+    (import ./docker self.inputs.khepri)
+    ''
+      Imports my [Khepri fork](https://github.com/matt1432/khepri), sets default
+      options such as BTRFS filesystem and adds an update script for images.
+    '';
+
+  esphome-plus =
+    module
+    (import ./esphome-plus)
+    ''
+      Fixes a bug with compilation of m5-atom-stack firmware and allows declaring
+      firmware configurations in nix code.
+    '';
+
+  ha-plus =
+    module
+    (import ./ha-plus)
+    ''
+      Extends the home-assistant options to allow declaring the content of specific
+      configuration files in the home-assistant configuration directory such as
+      custom sentences through nix code.
+    '';
+
+  kmscon =
+    module
+    (import ./kmscon)
+    ''
+      Extends the kmscon options to add more descriptive ones.
+    '';
+
+  meta =
+    module
+    (import ./meta)
+    ''
+      Adds options to declare the documentation of my devices that will be
+      generated to `./configurations/README.md`.
+    '';
+
+  nvidia =
+    module
+    (import ./nvidia)
+    ''
+      Abstracts NVIDIA options and miscellaneous fixes behind simpler options.
+    '';
+
+  plymouth =
+    module
+    (import ./plymouth)
+    ''
+      Sets some boot options to make the boot sequence cleaner.
+    '';
+
+  server =
+    module
+    (import ./server)
+    ''
+      Sets up sshd, tailscale and related configurations.
+    '';
+
+  tmux =
+    module
+    (import ./tmux)
+    ''
+      Uses the home-manager tmux module to declare my custom configuration and
+      links it to `/etc` to set it globally.
+    '';
+
+  wyoming-plus =
+    module
+    (import ./wyoming-plus)
+    ''
+      Extends the `wyoming.openwakeword` options to allow declaring flags used
+      by the [fork](https://github.com/rhasspy/wyoming-openwakeword/pull/17)
+      of `wyoming-openwakeword` exposed by this module.
+    '';
 }