feat(helpers/text): add headings and descriptions

README.md

@@ -1,5 +1,9 @@
+# readme
+## generated-files
 This flake uses the [files flake-parts module](https://flake.parts/options/files.html) to generate documentation.
 The list of generated files are:
 - [docs/cheatsheet.md](docs/cheatsheet.md)
 - [README.md](README.md)
+## helpers
+### text-helper
 The option `text.<name> supports either a string or a submodule with attributes order and parts. The parts attribute can either be a string, which will get concatenated in the order laid out in `text.<name>.order`, or can itself have the attributes order and parts, in which case it will be evaluated recursively.

docs/cheatsheet.md

@@ -1 +1,2 @@
+# cheatsheet
 `__curPos.file` will give the full evaluated path of the nix file it is called in. See [this issue](https://github.com/NixOS/nix/issues/5897#issuecomment-1012165198) for more information.

modules/helpers/text.nix

@@ -1,10 +1,13 @@
 { lib, ... }:
 let
   inherit (lib)
+    optional
+    concatStrings
+    flatten
     mkOption
     mapAttrs
     isString
-    pipe
+    replicate
     flip
     getAttr
     concatStringsSep
@@ -20,29 +23,52 @@ let
     str
     (submodule {
       options = {
+        heading = mkOption {
+          type = str;
+          default = "";
+        };
+        description = mkOption {
+          type = str;
+          default = "";
+        };
         order = mkOption { type = listOf str; };
         parts = mkOption { type = lazyAttrsOf textType; };
       };
     })
   ];
-  recurseAttrs =
-    value:
+  mkListFromAttrs =
+    prefix:
+    { name, value }:
+    let
+      sectionHeading = result: "${concatStrings (replicate prefix "#")} ${result}";
+    in
     if isString value then
+      [
+        (sectionHeading name)
         value
+      ]
     else
       # TODO: handle order being empty
-      # TODO: add headings for each part with possible option to disable
-      pipe value.order [
-        (map (flip getAttr value.parts))
-        (map recurseAttrs)
-        (concatStringsSep "\n")
+      flatten [
+        [
+          (sectionHeading (if value.heading == "" then name else value.heading))
+        ]
+        (optional (value.description != "") value.description)
+        (map (mkListFromAttrs (prefix + 1)) (
+          map (x: {
+            name = x;
+            value = flip getAttr value.parts x;
+          }) value.order
+        ))
       ];
 in
 {
   options.text = mkOption {
     default = { };
     type = lazyAttrsOf textType;
-    apply = mapAttrs (_: recurseAttrs);
+    apply = mapAttrs (
+      name: value: concatStringsSep "\n" (flatten (mkListFromAttrs 1 { inherit name value; }))
+    );
   };
   config.text.readme.parts.helpers.parts.text-helper =
     "The option `text.<name> supports either a string or a submodule with attributes order and parts. The parts attribute can either be a string, which will get concatenated in the order laid out in `text.<name>.order`, or can itself have the attributes order and parts, in which case it will be evaluated recursively.";