extract module top-level comment to docs

ci.nix

@@ -18,7 +18,9 @@ let
     }).outputs.default;
   tests = import ./tests/ci.nix;
   jobs =
-    (genAttrs devices (name: for-device name)) // tests // {
+    (genAttrs devices (name: for-device name)) //
+    tests //
+    {
       buildEnv = (import liminix {
         inherit nixpkgs  borderVmConf;
         device = import (liminix + "/devices/qemu");
@@ -26,7 +28,10 @@ let
       }).buildEnv;
       doc = pkgs.stdenv.mkDerivation {
         name = "liminix-doc";
-        nativeBuildInputs = with pkgs; [ gnumake sphinx  fennel luaPackages.dkjson ];
+        nativeBuildInputs = with pkgs; [
+          gnumake sphinx
+          fennel luaPackages.lyaml
+        ];
         src = ./doc;
         buildPhase = ''
           cat ${(import ./doc/extract-options.nix).doc} | fennel --correlate parse-options.fnl > modules.rst

doc/extract-options.nix

@@ -49,7 +49,8 @@ let
   o = builtins.map spliceServiceDefn
     (pkgs.lib.optionAttrSetToDocList eval.options);
 in {
-  doc = pkgs.writeText "options.json"
-    (builtins.unsafeDiscardStringContext (builtins.toJSON o))
-  ;
+  doc = pkgs.writeText "options.yaml" ''
+    # ${./..}
+    ${builtins.toJSON o}
+  '';
 }

doc/parse-options.fnl

@@ -1,4 +1,4 @@
-(local json (require :dkjson))
+(local yaml (require :lyaml))
 
 (local { : view } (require :fennel))
 
@@ -8,6 +8,17 @@
     (print basename)
     (print (string.rep "=" len))))
 
+(fn read-preamble [pathname]
+  (if (= (pathname:sub 1 1) "/")
+      (let [pathname (if (string.match pathname ".nix$")
+                         pathname
+                         (.. pathname "/default.nix"))]
+        (with-open [f (assert (io.open pathname :r))]
+          (accumulate [lines ""
+                       l (f:lines)
+                       :until (not (= (string.sub l 1 2) "##"))]
+            (.. lines (string.gsub l "^## *" "") "\n"))))))
+
 (fn strip-newlines [text]
   (and text
        (-> text
@@ -54,15 +65,15 @@
   (table.sort module (fn [a b] (< a.name b.name)))
   module)
 
-(let [raw (json.decode (io.read "*a"))
+(let [raw (yaml.load (io.read "*a"))
       modules {}]
   (each [_ option (ipairs raw)]
-    (let [[path] option.declarations
-          e (or (. modules path) [])]
+    (each [_ path (ipairs option.declarations)]
+      (let [e (or (. modules path) [])]
         (table.insert e option)
-      (tset modules path e)))
+        (tset modules path e))))
   (each [name module (pairs modules)]
-    (print (headline name))
+    (print (read-preamble name))
     (let [options (sort-options module)]
       (each [_ o (ipairs options)]
         (if (= o.type "parametrisable s6-rc service definition")

modules/bridge/default.nix

@@ -1,4 +1,5 @@
 ## Bridge module
+## =============
 ##
 ##  Allows creation of Layer 2 software "bridge" network devices.  A
 ##  common use case is to merge together a hardware Ethernet device