From dc4b7ebffdfca0ae1b1ba4b446ced53993ae28eb Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Fri, 11 Aug 2023 21:12:57 +0100
Subject: [PATCH] module docs: print examples

---
 ci.nix                |  5 ++--
 doc/parse-options.fnl | 58 ++++++++++++++++++++-----------------------
 modules/kernel.nix    | 10 +++++++-
 3 files changed, 39 insertions(+), 34 deletions(-)

diff --git a/ci.nix b/ci.nix
index 1f7d60f9..fdfffd74 100644
--- a/ci.nix
+++ b/ci.nix
@@ -34,12 +34,13 @@ let
         ];
         src = ./doc;
         buildPhase = ''
-          cat ${(import ./doc/extract-options.nix).doc} | fennel --correlate parse-options.fnl > modules.rst
+          cat ${(import ./doc/extract-options.nix).doc} > options.json
+          cat options.json | fennel --correlate parse-options.fnl > modules.rst
           make html
         '';
         installPhase = ''
           mkdir -p $out/nix-support $out/share/doc/
-          # (cd _build && tar cf $out/share/doc/liminix_manual.tar html)
+          cp modules.rst options.json $out
           cp -a _build/html $out/share/doc/liminix
           echo "file source-dist \"$out/share/doc/liminix\"" \
               > $out/nix-support/hydra-build-products
diff --git a/doc/parse-options.fnl b/doc/parse-options.fnl
index ca1747ab..77b329d2 100644
--- a/doc/parse-options.fnl
+++ b/doc/parse-options.fnl
@@ -20,38 +20,44 @@
             (.. lines (string.gsub l "^## *" "") "\n"))))))
 
 (fn strip-newlines [text]
-  (and text
-       (-> text
-           (string.gsub "\n([^\n])" " %1")
-           (string.gsub "\n\n+" "\n"))))
+  (-> text
+      (string.gsub "\n([^\n])" " %1")
+      (string.gsub "\n\n+" "\n")))
 
 (fn indent [n text]
   (let [margin (string.rep " " n)]
-    (.. margin (string.gsub text "\n +" (.. "\n" margin )))))
+    (.. margin (string.gsub (or text "") "\n +" (.. "\n" margin )))))
+
+(fn indent-literal [n text]
+  (let [margin (string.rep " " n)]
+    (.. margin (string.gsub (or text "") "\n" (.. "\n" margin )))))
 
 (fn extract-text [description]
-  (and description
-;       (do (print (view description)) true)
-       (-> (match description
-             { :type "literalExpression" : text } text
-             {} nil
-             nil nil
-             t description)
-           strip-newlines)))
+  (match description
+    { :_type "literalExpression" : text } text
+    (where s (= (type s) "string")) description
+    _ nil))
 
 (fn print-option [o offset]
   (let [i (or offset 0)]
     (print (indent i (.. " * option ``" o.name "``")))
-    (print (indent (+ 4 i)
-                   (or (extract-text o.description) "(no description)")))
+    (case (-?> o.description extract-text strip-newlines)
+          descr (print (indent (+ 4 i) descr)))
     (print)
     (print (indent (+ 4 i) (.. "**type** " o.type "\n")))
-    (print (indent (+ 4 i)
-                   (.. "**default** "
-                       (or (extract-text (?. o :default)) "(none)")
-                       "\n"
-                       )))
-    (print )))
+    (when o.example
+      (print (indent (+ 4 i) "**example**")) (print)
+      (print (indent (+ 4 i) ".. code-block:: nix"))
+      (print)
+      (print (indent-literal (+ 8 i) (extract-text o.example)) "\n")
+      (print))
+
+    (when (extract-text o.default)
+      (print (indent (+ 4 i) "**default**")) (print)
+      (print (indent (+ 4 i) ".. code-block:: nix"))
+      (print)
+      (print (indent-literal (+ 8 i) (extract-text o.default)) "\n")
+      (print))))
 
 (fn print-service [o]
   (print (.. " * service ``" o.name "``"))
@@ -83,13 +89,3 @@
           (if (= o.type "parametrisable s6-rc service definition")
               (print-service o)
               (print-option o)))))))
-
-;; for each element el, add to table modules keyed on
-;; el.declarations
-
-;; for each value in modules
-;;   print title
-;;   elements = (sort elements on el.name)
-;;   for each el in elements
-;;     is option or service? print whichever
-;;
diff --git a/modules/kernel.nix b/modules/kernel.nix
index 0d412a65..d9e51785 100644
--- a/modules/kernel.nix
+++ b/modules/kernel.nix
@@ -1,6 +1,7 @@
 ## Kernel-related options
 ## ======================
-
+##
+##
 
 { lib, pkgs, config, ...}:
 let
@@ -32,6 +33,13 @@ in {
           but sometimes other strings are also used.
         '';
         type = types.attrsOf types.nonEmptyStr;
+        example = lib.literalExpression ''
+          {
+            BRIDGE = "y";
+            TMPFS = "y";
+            FW_LOADER_USER_HELPER = "n";
+          };
+        '';
       };
     };
   };