pkgs/nixfiles-docs-generate-options-md: Automatically generate module options docs

docs/pages/Options.md

@@ -0,0 +1,3 @@
+# Options
+
+This page is generated on build time.

docs/pages/Options/index.md

@@ -1 +0,0 @@
-# Options

docs/pages/index.md

@@ -1 +1,6 @@
+---
+hide:
+  - navigation
+---
+
 # Home

pkgs/nixfiles-docs-generate-options-md/default.nix

@@ -0,0 +1,8 @@
+{
+  pkgs,
+}:
+
+pkgs.clerie-build-support.writePythonScript {
+  name = "nixfiles-docs-generate-options-md";
+  text = builtins.readFile ./nixfiles-docs-generate-options-md.py;
+}

pkgs/nixfiles-docs-generate-options-md/nixfiles-docs-generate-options-md.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+from pathlib import Path
+
+parser = argparse.ArgumentParser(prog="generate-options-docs.py")
+parser.add_argument("options_json_file", type=Path)
+
+args = parser.parse_args()
+
+module_options = json.loads(args.options_json_file.read_text())
+
+print("""---
+hide:
+  - navigation
+---
+
+# Options
+
+""")
+
+def format_option_value(option_value):
+    if not isinstance(option_value, dict):
+        option_value = {
+                "_type": "literalExpression",
+                "text": str(option_value),
+        }
+
+    match option_value["_type"]:
+        case "literalExpression":
+            if "\n" in option_value["text"]:
+                return f"```\n{option_value['text']}\n```"
+            else:
+                return f"```\n{option_value['text']}\n```"
+
+        case "literalMD":
+            return option_value["text"]
+        case other_value_type:
+            raise Exception(f"Unhandle option value type {other_value_type}")
+
+
+def print_option(option):
+    print(f"## `{option['name']}`")
+    print("")
+    if "description" in option and option["description"] is not None:
+        print(option['description'])
+        print("")
+    if "type" in option:
+        print("**Type:**")
+        print(f"`{option['type']}`")
+        print("")
+    if "default" in option:
+        print(f"**Default:**")
+        print(format_option_value(option['default']))
+        print("")
+    if "example" in option:
+        print(f"**Example:**")
+        print(format_option_value(option['example']))
+        print("")
+
+for option in module_options:
+    print_option(option)

pkgs/nixfiles-docs/default.nix

@@ -1,6 +1,8 @@
 {
   stdenv,
-  mkdocs-material
+  mkdocs-material,
+  nixfiles-docs-generate-options-md,
+  nixfiles-docs-options,
 }:
 
 stdenv.mkDerivation {
@@ -10,9 +12,11 @@ stdenv.mkDerivation {
 
   buildInputs = [
     mkdocs-material
+    nixfiles-docs-generate-options-md
   ];
 
   buildPhase = ''
+    nixfiles-docs-generate-options-md ${nixfiles-docs-options} > pages/Options.md
     python3 -m mkdocs build
   '';
 

pkgs/overlay.nix

@@ -28,6 +28,7 @@ final: prev: {
   nix-remove-result-links = final.callPackage ./nix-remove-result-links {};
   nixfiles-auto-install = final.callPackage ./nixfiles/nixfiles-auto-install.nix {};
   nixfiles-docs = final.python3.pkgs.callPackage ./nixfiles-docs {};
+  nixfiles-docs-generate-options-md = final.callPackage ./nixfiles-docs-generate-options-md {};
   nixfiles-docs-options = final.callPackage ./nixfiles-docs-options {};
   nixfiles-generate-config = final.callPackage ./nixfiles/nixfiles-generate-config.nix {};
   nixfiles-generate-backup-secrets = final.callPackage ./nixfiles/nixfiles-generate-backup-secrets.nix {};