create static docs site with module options

docs/.gitignore

@@ -0,0 +1,5 @@
+public/
+resources/
+*.lock
+options.json
+content/modules/*.md

docs/assets/_custom.scss

@@ -0,0 +1,91 @@
+$foreground-color: #f8f8f2;
+$background-color: #333333;
+
+// create an arrow rotated by $angle
+@mixin arrow($angle) {
+  content: "";
+  display: inline-block;
+  position: fixed;
+  // size
+  padding: 3px;
+  // position
+  margin: 18px 15px;
+  border: solid $background-color;
+  border-width: 0 2px 2px 0;
+
+  transform: rotate($angle);
+  -webkit-transform: rotate($angle);
+}
+
+details {
+  padding: 0rem 1rem !important;
+  margin: 1rem;
+  padding: 0 !important;
+
+  > summary {
+    padding: 0rem !important;
+    margin: 0 !important;
+
+    // do not show arrow bullet point
+    list-style: none;
+    ::-webkit-details-marker {
+      display: none;
+    }
+
+    // replace builtin arrows with custom ones
+    pre {
+      display: inline-block;
+      width: 100%;
+      margin: 0 !important;
+      padding-left: 42px !important;
+      vertical-align: middle;
+    }
+    &:before {
+      @include arrow(-45deg);
+    }
+  }
+
+  &[open] summary:before {
+      @include arrow(45deg);
+  }
+
+  table, tbody {
+    // fill entire width
+    width: 100% !important;
+    display: table;
+    margin: 0 !important;
+
+    tr {
+      // make code blocks a little smaller
+      pre {
+        margin: 0 !important;
+        padding: 0.2rem !important;
+
+        &.highlight {
+          color: $foreground-color;
+          background-color: $background-color;
+        };
+
+        code {
+          vertical-align: text-bottom;
+          padding-left: 0.2rem !important;
+        }
+      }
+
+      // field name
+      td:first-child {
+        font-weight: bold;
+        font-size: 90%;
+
+        width: 8em;
+        min-width: 8em;
+        max-width: 8em;
+        word-break: break-all;
+      }
+    }
+  }
+}
+
+aside.book-menu span {
+  font-weight: bold;
+}

docs/config.toml

@@ -0,0 +1,10 @@
+title = "kubenix"
+theme = "hugo-book"
+baseURL = "https://kubenix.org/"
+
+[params]
+BookLogo = "logo.svg"
+BookRepo = "https://github.com/hall/kubenix"
+BookSection = '*'
+# most pages at this time are auto-generated so editing doesn't make sense
+# BookEditPath = 'edit/main/docs'

docs/content/_index.md

@@ -0,0 +1 @@
+../../README.md

docs/default.nix

@@ -0,0 +1,122 @@
+# adapted from: https://discourse.nixos.org/t/franken-script-to-generate-nixos-options-docs-with-custom-modules/1674/4
+{
+  pkgs,
+  options,
+}: let
+  extraSources = [];
+  lib = pkgs.lib;
+
+  optionsListVisible =
+    lib.filter (opt: opt.visible && !opt.internal)
+    (lib.optionAttrSetToDocList options);
+
+  # Replace functions by the string <function>
+  substFunction = x:
+    if builtins.isAttrs x
+    then lib.mapAttrs (name: substFunction) x
+    else if builtins.isList x
+    then map substFunction x
+    else if lib.isFunction x
+    then "<function>"
+    else if isPath x
+    then toString x
+    else x;
+
+  isPath = x: (builtins.typeOf x) == "path";
+
+  optionsListDesc = lib.flip map optionsListVisible (
+    opt:
+      opt
+      // {
+        description = let
+          attempt = builtins.tryEval opt.description;
+        in
+          if attempt.success
+          then attempt.value
+          else "N/A";
+        declarations = map stripAnyPrefixes opt.declarations;
+      }
+      // lib.optionalAttrs (opt ? example) {
+        example = substFunction opt.example;
+      }
+      // lib.optionalAttrs (opt ? default) {
+        default = substFunction opt.default;
+      }
+      // lib.optionalAttrs (opt ? type) {
+        type = substFunction opt.type;
+      }
+      // lib.optionalAttrs
+      (opt ? relatedPackages && opt.relatedPackages != [])
+      {
+        relatedPackages = genRelatedPackages opt.relatedPackages;
+      }
+  );
+
+  genRelatedPackages = packages: let
+    unpack = p:
+      if lib.isString p
+      then {name = p;}
+      else if lib.isList p
+      then {path = p;}
+      else p;
+    describe = args: let
+      title = args.title or null;
+      name = args.name or (lib.concatStringsSep "." args.path);
+      path = args.path or [args.name];
+      package =
+        args.package
+        or (lib.attrByPath path
+          (throw
+            "Invalid package attribute path '${toString path}'")
+          pkgs);
+    in
+      "<listitem>"
+      + "<para><literal>${lib.optionalString (title != null)
+        "${title} aka "}pkgs.${name} (${package.meta.name})</literal>"
+      + lib.optionalString (!package.meta.available)
+      " <emphasis>[UNAVAILABLE]</emphasis>"
+      + ": ${package.meta.description or "???"}.</para>"
+      + lib.optionalString (args ? comment)
+      "\n<para>${args.comment}</para>"
+      + lib.optionalString (package.meta ? longDescription)
+      "\n<programlisting>${package.meta.longDescription}"
+      + "</programlisting>"
+      + "</listitem>";
+  in "<itemizedlist>${lib.concatStringsSep "\n" (map (p:
+    describe (unpack p))
+  packages)}</itemizedlist>";
+
+  optionLess = a: b: let
+    ise = lib.hasPrefix "enable";
+    isp = lib.hasPrefix "package";
+    cmp =
+      lib.splitByAndCompare ise lib.compare
+      (lib.splitByAndCompare isp lib.compare lib.compare);
+  in
+    lib.compareLists cmp a.loc b.loc < 0;
+
+  prefixesToStrip = map (p: "${toString p}/") ([../../..] ++ extraSources);
+  stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip;
+
+  ###############################################################################
+
+  # This is the REAL meat of what we were after.
+  # Output this however you want.
+  optionsList = lib.sort optionLess optionsListDesc;
+
+  optionsJSON = builtins.unsafeDiscardStringContext (builtins.toJSON
+    (builtins.listToAttrs (map
+      (o: {
+        name = o.name;
+        value = removeAttrs o [
+          # Select the fields you want to drop here:
+          "name"
+          "visible"
+          "internal"
+          "loc"
+          "readOnly"
+        ];
+      })
+      optionsList)));
+in
+  pkgs.writeText "options.json" optionsJSON

docs/layouts/partials/details.html

@@ -0,0 +1,40 @@
+{{ $name := index . "name" }}
+{{ $option := index . "option" }}
+{{ $repo := index . "repo" }}
+
+{{ $path := path.Join (after 2 (split (index $option.declarations 0) "/")) }}
+
+<details id="{{ $name }}">
+    <summary>
+        <pre>{{ $name }}</pre>
+    </summary>
+
+    <table>
+        <tr>
+            <td>Description</td>
+            <td>{{ $option.description }}</td>
+        </tr>
+
+        <tr>
+            <td>Type</td>
+            <td><pre>{{ $option.type }}</pre></td>
+        </tr>
+
+        <tr>
+            <td>Default</td>
+            <td>{{ partial "highlight" $option.default }}</td>
+        </tr>
+
+        {{ with $option.example }}
+        <tr>
+            <td>Example</td>
+            <td>{{ partial "highlight" . }}</td>
+        </tr>
+        {{ end }}
+
+        <tr>
+            <td>Declared in</td>
+            <td><a href="{{ $repo }}/blob/main/{{ $path }}" target="_blank">{{ $path }}</a></td>
+        </tr>
+    </table>
+</details>

docs/layouts/partials/docs/inject/body.html

@@ -0,0 +1,24 @@
+<script>
+  window.onload = function(){
+    // open details of option in URL fragment
+    document.getElementById(decodeURI(window.location.hash.substring(1)))?.setAttribute("open", "");
+
+    var options = document.getElementsByTagName('details');
+    for(var i = 0; i < options.length; i++) {
+        options[i].getElementsByTagName("summary")[0].onclick = function() {
+
+            // set URL fragment to option id
+            window.location.hash = this.parentElement.id;
+
+            // is current panel open, return immediately as it's just being closed
+            if (this.parentElement.hasAttribute("open")) return;
+
+            // collapse all other options
+            for(var j = 0; j < options.length; j++) {
+                options[j].removeAttribute("open");
+            }
+        };
+    }
+
+  }; 
+</script>

docs/layouts/partials/docs/inject/head.html

@@ -0,0 +1 @@
+<link rel="icon" href="/logo.svg">

docs/layouts/partials/highlight.html

@@ -0,0 +1,10 @@
+{{ $text := . }}
+
+{{/* if text is a multiline string add nix's double single-quotes */}}
+{{ if in $text "\n" }}
+  {{ $text = print "''\n  " (strings.TrimSuffix "  " (replace $text "\n" "\n  ") ) "''" }}
+{{ else }}
+  {{ $text = jsonify $text }}
+{{ end }}
+
+<pre class="highlight"><code>{{ $text }}</code></pre>

docs/layouts/shortcodes/options.html

@@ -0,0 +1,22 @@
+{{ $module := $.Page.File.BaseFileName }}
+{{ $repo := $.Site.Params.BookRepo }}
+{{ range $name, $option := .Site.Data.options }}
+
+  {{/* some module options are nested under others */}}
+  {{ if and (hasPrefix $name "kubernetes.helm.") }}
+    {{ if (eq $module "helm") }}
+      {{ partial "details" (dict "name" $name "option" $option "repo" $repo) }}
+    {{ end }}
+  {{ else }}
+
+     {{/* only show options for the current module */}}
+     {{/* but don't list _all_ kubernetes resources */}}
+     {{ if and 
+         (not (hasPrefix $name "kubernetes.api.resources."))
+         (hasPrefix $name (print $module ".")) 
+     }}
+         {{ partial "details" (dict "name" $name "option" $option "repo" $repo) }}
+     {{ end }}
+  {{ end }}
+
+{{ end }}

docs/themes/hugo-book

@@ -0,0 +1 @@
+Subproject commit 317ccae23b73f5e49d7341ad57227bd64a89ab38