add preamble text to each service-providing-module

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,3 +1,14 @@
+## Bridge module
+## =============
+##
+##  Allows creation of Layer 2 software "bridge" network devices.  A
+##  common use case is to merge together a hardware Ethernet device
+##  with one or more WLANs so that several local devices appear to be
+##  on the same network. Create a ``primary`` service to specify the
+##  new device, and a ``members`` service to add constituent devices
+##  to it.
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;

modules/dnsmasq/default.nix

@@ -1,3 +1,10 @@
+## Dnsmasq
+## =======
+##
+## This module includes a service to provide DNS, DHCP, and IPv6
+## router advertisement for the local network.
+
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;

modules/firewall/default.nix

@@ -1,3 +1,9 @@
+## Firewall
+## ========
+##
+## Provides a service to create an nftables ruleset based on
+## configuration supplied to it.
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;

modules/hardware.nix

@@ -7,13 +7,18 @@ in {
     };
     hardware = {
       dts = {
-        src = mkOption { type = types.path; };
+        src = mkOption {
+          type = types.path;
+          description = "Path to the device tree source (usually from OpenWrt)";
+        };
         includes = mkOption {
           default = [];
+          description = "List of directories to search for DTS includes (.dtsi files)";
           type = types.listOf types.path;
         };
       };
       defaultOutput = mkOption {
+        description = "\"Default\" output: what gets built for this device when outputs.default is requested. Typically this is \"flashimage\" or \"vmroot\"";
         type = types.nonEmptyStr;
       };
       flash = {
@@ -22,13 +27,31 @@ in {
         # kernel uimage and root fs. Not the entire flash, as
         # that often also contains the bootloader, data for
         # for wireless devices, etc
-        address = mkOption { type = types.str; };
-        size = mkOption { type = types.str; };
-        eraseBlockSize = mkOption { type = types.str; };
+        address = mkOption {
+          description = ''
+            Start address of whichever partition (often
+            called "firmware") we're going to overwrite with our
+            kernel uimage and root fs. Usually not the entire flash, as
+            we don't want to clobber the bootloader, calibration data etc
+          '';
+          type = types.str;
+        };
+        size = mkOption {
+          type = types.str;
+          description = "Size in bytes of the firmware partition";
+        };
+        eraseBlockSize = mkOption {
+          description = "Flash erase block size in bytes";
+          type = types.str;
+        };
       };
       loadAddress = mkOption { default = null; };
       entryPoint = mkOption { };
       radios = mkOption {
+        description = ''
+          Kernel modules (from mac80211 package) required for the
+          wireless devices on this board
+        '';
         type = types.listOf types.str;
         default = [];
         example = ["ath9k" "ath10k"];

modules/hostapd/default.nix

@@ -1,3 +1,16 @@
+## Hostapd
+## =======
+##
+## Hostapd (host access point daemon) enables a wireless network
+## interface to act as an access point and authentication server,
+## providing IEEE 802.11 access point management, and IEEE
+## 802.1X/WPA/WPA2/EAP Authenticators. In less technical terms,
+## this service is what you need for your Liminix device to
+## provide a wireless network that clients can connect to.
+##
+## If you have more than one wireless network interface (e.g.
+## wlan0, wlan1) you can run an instance of hostapd on each of them.
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;

modules/ntp/default.nix

@@ -1,3 +1,11 @@
+## NTP
+## ===
+##
+## A network time protocol implementation so that your Liminix device
+## may synchronize its clock with an accurate time source, and
+## optionally also provide time service to its peers. The
+## implementation used in Liminix is Chrony
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;

modules/ppp/default.nix

@@ -1,3 +1,12 @@
+## PPP
+## ===
+##
+## A rudimentary PPPoE (PPP over Ethernet) configuration to address
+## the case where your Liminix device is connected to an upstream
+## network using PPPoE. This is typical for UK broadband connections
+## (except "cable"), and common in some other localities as well: ask
+## your ISP if this is you.
+
 { lib, pkgs, config, ...}:
 let
   inherit (lib) mkOption types;