From 615c2de537949d3ef7c9955dffc877ecdd4049c1 Mon Sep 17 00:00:00 2001 From: Daniel Barlow 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