From 615c2de537949d3ef7c9955dffc877ecdd4049c1 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Mon, 7 Aug 2023 22:14:58 +0100
Subject: [PATCH] extract module top-level comment to docs

---
 ci.nix                     |  9 +++++++--
 doc/extract-options.nix    |  7 ++++---
 doc/parse-options.fnl      | 25 ++++++++++++++++++-------
 modules/bridge/default.nix |  1 +
 4 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/ci.nix b/ci.nix
index dbc9fb7..1f7d60f 100644
--- a/ci.nix
+++ b/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
diff --git a/doc/extract-options.nix b/doc/extract-options.nix
index 5ac00bf..8c2dcac 100644
--- a/doc/extract-options.nix
+++ b/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}
+  '';
 }
diff --git a/doc/parse-options.fnl b/doc/parse-options.fnl
index d8f0913..508e72d 100644
--- a/doc/parse-options.fnl
+++ b/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) [])]
-      (table.insert e option)
-      (tset modules path e)))
+    (each [_ path (ipairs option.declarations)]
+      (let [e (or (. modules path) [])]
+        (table.insert e option)
+        (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")
diff --git a/modules/bridge/default.nix b/modules/bridge/default.nix
index 3fdfaf9..7d7e724 100644
--- a/modules/bridge/default.nix
+++ b/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