Merge pull request NixOS#209501 from sandydoo/improve/fix-commonmark-…

…doc-isues

nixos/make-options-doc: skip re-escaping literal expressions

nixos/lib/make-options-doc/generateDoc.py

@@ -21,18 +21,22 @@
 
 args = parser.parse_args()
 
-# Pretty-print certain Nix types, like literal expressions.
-def render_types(obj):
-    if '_type' not in obj: return obj
+class OptionsEncoder(json.JSONEncoder):
+    def encode(self, obj):
+        # Unpack literal expressions and other Nix types.
+        # Don't escape the strings: they were escaped when initially serialized to JSON.
+        if isinstance(obj, dict):
+            _type = obj.get('_type')
+            if _type is not None:
+                if _type == 'literalExpression' or _type == 'literalDocBook':
+                    return obj['text']
 
-    _type = obj['_type']
-    if _type == 'literalExpression' or _type == 'literalDocBook':
-        return obj['text']
+                if _type == 'derivation':
+                    return obj['name']
 
-    if _type == 'derivation':
-        return obj['name']
+                raise Exception(f'Unexpected type `{_type}` in {json.dumps(obj)}')
 
-    raise Exception(f'Unexpected type `{_type}` in {json.dumps(obj)}')
+        return super().encode(obj)
 
 def generate_commonmark(options):
     for (name, value) in options.items():
@@ -49,14 +53,14 @@ def generate_commonmark(options):
         if 'default' in value:
             print('*_Default_*')
             print('```')
-            print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
+            print(json.dumps(value['default'], cls=OptionsEncoder, ensure_ascii=False, separators=(',', ':')))
             print('```')
         print()
         print()
         if 'example' in value:
             print('*_Example_*')
             print('```')
-            print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
+            print(json.dumps(value['example'], cls=OptionsEncoder, ensure_ascii=False, separators=(',', ':')))
             print('```')
         print()
         print()
@@ -76,7 +80,7 @@ def generate_asciidoc(options):
             print('Default::')
             print('+')
             print('----')
-            print(json.dumps(value['default'], ensure_ascii=False, separators=(',', ':')))
+            print(json.dumps(value['default'], cls=OptionsEncoder, ensure_ascii=False, separators=(',', ':')))
             print('----')
             print()
         else:
@@ -89,15 +93,15 @@ def generate_asciidoc(options):
             print('Example::')
             print('+')
             print('----')
-            print(json.dumps(value['example'], ensure_ascii=False, separators=(',', ':')))
+            print(json.dumps(value['example'], cls=OptionsEncoder, 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)
+    options = json.load(nix_options_json)
 
     if args.format == 'commonmark':
         generate_commonmark(options)