scripts/generate-options: refactor

- Extract the md syntax part into reusable functions
- Rename variables so their purpose becomes clearer

scripts/generate-options.py

@@ -1,5 +1,7 @@
 import json
 import sys
+from textwrap import indent
+from typing import Any, Mapping
 
 header = """
 # Mailserver options
@@ -35,45 +37,61 @@ groups = [
 ]
 
 
-def render_option_value(opt, attr):
+def md_literal(value: str) -> str:
-    if attr not in opt:
+    return f"`{value}`"
+
+
+def md_codefence(value: str, language: str = "nix") -> str:
+    return indent(
+        f"\n```{language}\n{value}\n```",
+        prefix=2 * " ",
+    )
+
+
+def render_option_value(option: Mapping[str, Any], key: str) -> str:
+    if key not in option:
         return ""
 
-    if isinstance(opt[attr], dict) and "_type" in opt[attr]:
+    if isinstance(option[key], dict) and "_type" in option[key]:
-        if opt[attr]["_type"] == "literalExpression":
+        if option[key]["_type"] == "literalExpression":
-            if "\n" in opt[attr]["text"]:
+            # multi-line codeblock
-                text = opt[attr]["text"].rstrip("\n")
+            if "\n" in option[key]["text"]:
-                res = f"\n```nix\n{text}\n```"
+                text = option[key]["text"].rstrip("\n")
+                value = md_codefence(text)
+            # inline codeblock
             else:
-                res = f"```{opt[attr]["text"]}```"
+                value = md_literal(option[key]["text"])
-        elif opt[attr]["_type"] == "literalMD":
+        # literal markdown
-            res = opt[attr]["text"]
+        elif option[key]["_type"] == "literalMD":
+            value = option[key]["text"]
         else:
-            assert RuntimeError(f"Unhandled option type {opt[attr]["_type"]}")
+            assert RuntimeError(f"Unhandled option type {option[key]['_type']}")
     else:
-        s = str(opt[attr])
+        text = str(option[key])
-        if s == "":
+        if text == "":
-            res = '`""`'
+            value = md_literal('""')
-        elif "\n" in s:
+        elif "\n" in text:
-            res = f"\n```\n{s.rstrip("\n")}\n```"
+            value = md_codefence(text.rstrip("\n"))
         else:
-            res = f"```{s}```"
+            value = md_literal(text)
 
-    return "- " + attr + ": " + res  # type: ignore
+    return f"- {key}: {value}"  # type: ignore
 
 
-def print_option(opt):
+def print_option(option):
-    if isinstance(opt["description"], dict) and "_type" in opt["description"]:  # mdDoc
+    if (
-        description = opt["description"]["text"]
+        isinstance(option["description"], dict) and "_type" in option["description"]
+    ):  # mdDoc
+        description = option["description"]["text"]
     else:
-        description = opt["description"]
+        description = option["description"]
     print(
         template.format(
-            key=opt["name"],
+            key=option["name"],
             description=description or "",
-            type=f"- type: ```{opt["type"]}```",
+            type=f"- type: {md_literal(option['type'])}",
-            default=render_option_value(opt, "default"),
+            default=render_option_value(option, "default"),
-            example=render_option_value(opt, "example"),
+            example=render_option_value(option, "example"),
         )
     )