create static docs site with module options

2025-12-12 08:00:06 +01:00 · 2022-08-28 15:22:43 -04:00 · 2022-08-28 15:22:43 -04:00 · e75b801a31
commit e75b801a31
parent e3127e8c14
24 changed files with 448 additions and 19 deletions
--- a/docs/default.nix
+++ b/docs/default.nix
@ -0,0 +1,122 @@
+# adapted from: https://discourse.nixos.org/t/franken-script-to-generate-nixos-options-docs-with-custom-modules/1674/4
+{
+  pkgs,
+  options,
+}: let
+  extraSources = [];
+  lib = pkgs.lib;
+
+  optionsListVisible =
+    lib.filter (opt: opt.visible && !opt.internal)
+    (lib.optionAttrSetToDocList options);
+
+  # Replace functions by the string <function>
+  substFunction = x:
+    if builtins.isAttrs x
+    then lib.mapAttrs (name: substFunction) x
+    else if builtins.isList x
+    then map substFunction x
+    else if lib.isFunction x
+    then "<function>"
+    else if isPath x
+    then toString x
+    else x;
+
+  isPath = x: (builtins.typeOf x) == "path";
+
+  optionsListDesc = lib.flip map optionsListVisible (
+    opt:
+      opt
+      // {
+        description = let
+          attempt = builtins.tryEval opt.description;
+        in
+          if attempt.success
+          then attempt.value
+          else "N/A";
+        declarations = map stripAnyPrefixes opt.declarations;
+      }
+      // lib.optionalAttrs (opt ? example) {
+        example = substFunction opt.example;
+      }
+      // lib.optionalAttrs (opt ? default) {
+        default = substFunction opt.default;
+      }
+      // lib.optionalAttrs (opt ? type) {
+        type = substFunction opt.type;
+      }
+      // lib.optionalAttrs
+      (opt ? relatedPackages && opt.relatedPackages != [])
+      {
+        relatedPackages = genRelatedPackages opt.relatedPackages;
+      }
+  );
+
+  genRelatedPackages = packages: let
+    unpack = p:
+      if lib.isString p
+      then {name = p;}
+      else if lib.isList p
+      then {path = p;}
+      else p;
+    describe = args: let
+      title = args.title or null;
+      name = args.name or (lib.concatStringsSep "." args.path);
+      path = args.path or [args.name];
+      package =
+        args.package
+        or (lib.attrByPath path
+          (throw
+            "Invalid package attribute path '${toString path}'")
+          pkgs);
+    in
+      "<listitem>"
+      + "<para><literal>${lib.optionalString (title != null)
+        "${title} aka "}pkgs.${name} (${package.meta.name})</literal>"
+      + lib.optionalString (!package.meta.available)
+      " <emphasis>[UNAVAILABLE]</emphasis>"
+      + ": ${package.meta.description or "???"}.</para>"
+      + lib.optionalString (args ? comment)
+      "\n<para>${args.comment}</para>"
+      + lib.optionalString (package.meta ? longDescription)
+      "\n<programlisting>${package.meta.longDescription}"
+      + "</programlisting>"
+      + "</listitem>";
+  in "<itemizedlist>${lib.concatStringsSep "\n" (map (p:
+    describe (unpack p))
+  packages)}</itemizedlist>";
+
+  optionLess = a: b: let
+    ise = lib.hasPrefix "enable";
+    isp = lib.hasPrefix "package";
+    cmp =
+      lib.splitByAndCompare ise lib.compare
+      (lib.splitByAndCompare isp lib.compare lib.compare);
+  in
+    lib.compareLists cmp a.loc b.loc < 0;
+
+  prefixesToStrip = map (p: "${toString p}/") ([../../..] ++ extraSources);
+  stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip;
+
+  ###############################################################################
+
+  # This is the REAL meat of what we were after.
+  # Output this however you want.
+  optionsList = lib.sort optionLess optionsListDesc;
+
+  optionsJSON = builtins.unsafeDiscardStringContext (builtins.toJSON
+    (builtins.listToAttrs (map
+      (o: {
+        name = o.name;
+        value = removeAttrs o [
+          # Select the fields you want to drop here:
+          "name"
+          "visible"
+          "internal"
+          "loc"
+          "readOnly"
+        ];
+      })
+      optionsList)));
+in
+  pkgs.writeText "options.json" optionsJSON