From a4c953df3bfc990f4d1148c71968653512b0c23b Mon Sep 17 00:00:00 2001
From: matt1432 <matt@nelim.org>
Date: Mon, 20 Jan 2025 11:06:01 -0500
Subject: [PATCH] docs: add script to generate some docs from nix attrs

---
 apps/default.nix                     | 12 +++++++++---
 apps/gen-docs/default.nix            | 10 ++++++++++
 apps/gen-docs/script.sh              | 12 ++++++++++++
 apps/gen-docs/templates/devShells.md | 11 +++++++++++
 configurations/README.md             |  2 +-
 devShells/default.nix                |  1 +
 packages/README.md                   |  2 +-
 7 files changed, 45 insertions(+), 5 deletions(-)
 create mode 100644 apps/gen-docs/default.nix
 create mode 100755 apps/gen-docs/script.sh
 create mode 100644 apps/gen-docs/templates/devShells.md

diff --git a/apps/default.nix b/apps/default.nix
index c514fa0f..1f960d3c 100644
--- a/apps/default.nix
+++ b/apps/default.nix
@@ -7,14 +7,20 @@
 
   buildApp = attrs: (pkgs.callPackage ./buildApp.nix ({} // inputs // attrs));
 
-  mkApp = file: {
+  mkNodeApp = file: {
     program = getExe (pkgs.callPackage file ({inherit buildApp;} // inputs));
     type = "app";
   };
 
-  mkApps = apps: listToAttrs (map (x: nameValuePair x (mkApp ./${x})) apps);
+  mkNodeApps = apps: listToAttrs (map (x: nameValuePair x (mkNodeApp ./${x})) apps);
 in
-  mkApps [
+  mkNodeApps [
     "extract-subs"
     "update-sources"
   ]
+  // {
+    gen-docs = {
+      program = getExe (pkgs.callPackage ./gen-docs {});
+      type = "app";
+    };
+  }
diff --git a/apps/gen-docs/default.nix b/apps/gen-docs/default.nix
new file mode 100644
index 00000000..5877a31d
--- /dev/null
+++ b/apps/gen-docs/default.nix
@@ -0,0 +1,10 @@
+{
+  writeShellApplication,
+  pandoc,
+  ...
+}:
+writeShellApplication {
+  name = "gen-docs";
+  runtimeInputs = [pandoc];
+  text = builtins.readFile ./script.sh;
+}
diff --git a/apps/gen-docs/script.sh b/apps/gen-docs/script.sh
new file mode 100755
index 00000000..da35361d
--- /dev/null
+++ b/apps/gen-docs/script.sh
@@ -0,0 +1,12 @@
+substitute() {
+    echo '' | pandoc --metadata-file <(
+        nix eval \
+            --impure \
+            --json \
+            .#"$1" \
+            --apply "(x: {attrs = builtins.mapAttrs (_: v: v.meta.description or \"\") x.\${builtins.currentSystem};})" |
+            jq -r
+    ) -t markdown --template "$2" -o "$3"
+}
+
+substitute "devShells" "./templates/devShells.md" "$FLAKE/devShells/README.md"
diff --git a/apps/gen-docs/templates/devShells.md b/apps/gen-docs/templates/devShells.md
new file mode 100644
index 00000000..4c4798a9
--- /dev/null
+++ b/apps/gen-docs/templates/devShells.md
@@ -0,0 +1,11 @@
+# devShells
+
+This directory contains every derivations for devShells exposed by this flake.
+
+## List of my devShells found in `self.devShells`
+
+| Name | Description |
+| ---- | ----------- |
+$for(attrs/pairs)$
+| $it.key$ | $it.value$ |
+$endfor$
diff --git a/configurations/README.md b/configurations/README.md
index 9dc0bf4f..ebea17b4 100644
--- a/configurations/README.md
+++ b/configurations/README.md
@@ -1,6 +1,6 @@
 # nixosConfigurations
 
-This directory keeps every device's main configuration file, their `hardware-configuration.nix` and some custom modules
+This directory contains every device's main configuration file, their `hardware-configuration.nix` and some custom modules
 unique to them.
 
 ## List of my Devices
diff --git a/devShells/default.nix b/devShells/default.nix
index be9270c9..3110e071 100644
--- a/devShells/default.nix
+++ b/devShells/default.nix
@@ -19,6 +19,7 @@
     text = ''
       # this command might fail but still updates the main lockfile
       npm update --package-lock-only || true
+
       hash="$(prefetch-npm-deps ./package-lock.json)"
       echo "$hash"
 
diff --git a/packages/README.md b/packages/README.md
index 2952ffdb..afd01486 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -1,6 +1,6 @@
 # Packages
 
-This directory encompasses every derivations for packages exposed by my flake.
+This directory contains every derivations for packages exposed by this flake.
 
 ## List of my packages found in `self.packages`