From dc4b7ebffdfca0ae1b1ba4b446ced53993ae28eb Mon Sep 17 00:00:00 2001 From: Daniel Barlow 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 1f7d60f..fdfffd7 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 ca1747a..77b329d 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 0d412a6..d9e5178 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"; + }; + ''; }; }; };