diff options
author | sandydoo <hey@sandydoo.me> | 2022-12-05 16:05:06 +0000 |
---|---|---|
committer | sandydoo <hey@sandydoo.me> | 2022-12-07 14:06:56 +0000 |
commit | 926afb6f1c9bcca568eaf12fdd9d16c138a26136 (patch) | |
tree | b04377652d7ad2058a1e31f5edc268051a3476fe /nixos/lib/make-options-doc/generateDoc.py | |
parent | 1792d2f5c5e4fc9d656a155f8e1d35fffbd1ecbc (diff) |
nixos/make-options-doc: pretty-print literals
Unlike the XML doc renderer, the AsciiDoc and CommonMark renderers don't pretty-print certain complex types, like literal expressions, DocBook literals, and derivations. These types are dumped into the documentation as JSON. This commit parses and unwraps these types when loading the JSON-formatted NixOS options. The AsciiDoc and CommonMark renders have also been combined into a single script to allow code reuse.
Diffstat (limited to 'nixos/lib/make-options-doc/generateDoc.py')
-rw-r--r-- | nixos/lib/make-options-doc/generateDoc.py | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/nixos/lib/make-options-doc/generateDoc.py b/nixos/lib/make-options-doc/generateDoc.py new file mode 100644 index 0000000000000..dffa8cd614012 --- /dev/null +++ b/nixos/lib/make-options-doc/generateDoc.py @@ -0,0 +1,106 @@ +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('<', '<').replace('>', '>')) + 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() + +# 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}`') + |