Merge pull request #204996 from sandydoo/improve/render-nix-types-in-commonmark

nixos/make-options-doc: pretty-print literals

4 files changed, 114 insertions, 68 deletions

diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index e097aa5eebd8e..694512115d40a 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -111,14 +111,16 @@ in rec {
   inherit optionsNix;
 
   optionsAsciiDoc = pkgs.runCommand "options.adoc" {} ''
-    ${pkgs.python3Minimal}/bin/python ${./generateAsciiDoc.py} \
-      < ${optionsJSON}/share/doc/nixos/options.json \
+    ${pkgs.python3Minimal}/bin/python ${./generateDoc.py} \
+      --format asciidoc \
+      ${optionsJSON}/share/doc/nixos/options.json \
       > $out
   '';
 
   optionsCommonMark = pkgs.runCommand "options.md" {} ''
-    ${pkgs.python3Minimal}/bin/python ${./generateCommonMark.py} \
-      < ${optionsJSON}/share/doc/nixos/options.json \
+    ${pkgs.python3Minimal}/bin/python ${./generateDoc.py} \
+      --format commonmark \
+      ${optionsJSON}/share/doc/nixos/options.json \
       > $out
   '';
 
diff --git a/nixos/lib/make-options-doc/generateAsciiDoc.py b/nixos/lib/make-options-doc/generateAsciiDoc.py
deleted file mode 100644
index 48eadd248c5a0..0000000000000
--- a/nixos/lib/make-options-doc/generateAsciiDoc.py
+++ /dev/null
@@ -1,37 +0,0 @@
-import json
-import sys
-
-options = json.load(sys.stdin)
-# TODO: declarations: link to github
-for (name, value) in options.items():
-    print(f'== {name}')
-    print()
-    print(value['description'])
-    print()
-    print('[discrete]')
-    print('=== details')
-    print()
-    print(f'Type:: {value["type"]}')
-    if 'default' in value:
-        print('Default::')
-        print('+')
-        print('----')
-        print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
-        print('----')
-        print()
-    else:
-        print('No Default:: {blank}')
-    if value['readOnly']:
-        print('Read Only:: {blank}')
-    else:
-        print()
-    if 'example' in value:
-        print('Example::')
-        print('+')
-        print('----')
-        print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
-        print('----')
-        print()
-    else:
-        print('No Example:: {blank}')
-    print()
diff --git a/nixos/lib/make-options-doc/generateCommonMark.py b/nixos/lib/make-options-doc/generateCommonMark.py
deleted file mode 100644
index bf487bd89c3f8..0000000000000
--- a/nixos/lib/make-options-doc/generateCommonMark.py
+++ /dev/null
@@ -1,27 +0,0 @@
-import json
-import sys
-
-options = json.load(sys.stdin)
-for (name, value) in options.items():
-    print('##', name.replace('<', '&lt;').replace('>', '&gt;'))
-    print(value['description'])
-    print()
-    if 'type' in value:
-        print('*_Type_*:')
-        print(value['type'])
-        print()
-    print()
-    if 'default' in value:
-        print('*_Default_*')
-        print('```')
-        print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
-        print('```')
-    print()
-    print()
-    if 'example' in value:
-        print('*_Example_*')
-        print('```')
-        print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
-        print('```')
-    print()
-    print()
diff --git a/nixos/lib/make-options-doc/generateDoc.py b/nixos/lib/make-options-doc/generateDoc.py
new file mode 100644
index 0000000000000..1fe4eb0253add
--- /dev/null
+++ b/nixos/lib/make-options-doc/generateDoc.py
@@ -0,0 +1,108 @@
+import argparse
+import json
+import sys
+
+formats = ['commonmark', 'asciidoc']
+
+parser = argparse.ArgumentParser(
+    description = 'Generate documentation for a set of JSON-formatted NixOS options'
+)
+parser.add_argument(
+    'nix_options_path',
+    help = 'a path to a JSON file containing the NixOS options'
+)
+parser.add_argument(
+    '-f',
+    '--format',
+    choices = formats,
+    required = True,
+    help = f'the documentation format to generate'
+)
+
+args = parser.parse_args()
+
+# Pretty-print certain Nix types, like literal expressions.
+def render_types(obj):
+    if '_type' not in obj: return obj
+
+    _type = obj['_type']
+    if _type == 'literalExpression' or _type == 'literalDocBook':
+        return obj['text']
+
+    if _type == 'derivation':
+        return obj['name']
+
+    raise Exception(f'Unexpected type `{_type}` in {json.dumps(obj)}')
+
+def generate_commonmark(options):
+    for (name, value) in options.items():
+        print('##', name.replace('<', '&lt;').replace('>', '&gt;'))
+        print(value['description'])
+        print()
+        if 'type' in value:
+            print('*_Type_*')
+            print ('```')
+            print(value['type'])
+            print ('```')
+        print()
+        print()
+        if 'default' in value:
+            print('*_Default_*')
+            print('```')
+            print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
+            print('```')
+        print()
+        print()
+        if 'example' in value:
+            print('*_Example_*')
+            print('```')
+            print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
+            print('```')
+        print()
+        print()
+
+# TODO: declarations: link to github
+def generate_asciidoc(options):
+    for (name, value) in options.items():
+        print(f'== {name}')
+        print()
+        print(value['description'])
+        print()
+        print('[discrete]')
+        print('=== details')
+        print()
+        print(f'Type:: {value["type"]}')
+        if 'default' in value:
+            print('Default::')
+            print('+')
+            print('----')
+            print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
+            print('----')
+            print()
+        else:
+            print('No Default:: {blank}')
+        if value['readOnly']:
+            print('Read Only:: {blank}')
+        else:
+            print()
+        if 'example' in value:
+            print('Example::')
+            print('+')
+            print('----')
+            print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
+            print('----')
+            print()
+        else:
+            print('No Example:: {blank}')
+        print()
+
+with open(args.nix_options_path) as nix_options_json:
+    options = json.load(nix_options_json, object_hook=render_types)
+
+    if args.format == 'commonmark':
+        generate_commonmark(options)
+    elif args.format == 'asciidoc':
+        generate_asciidoc(options)
+    else:
+        raise Exception(f'Unsupported documentation format `--format {args.format}`')
+