mirror of
https://github.com/NixOS/nixpkgs.git
synced 2025-06-15 14:09:17 +03:00
926afb6f1c
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.
106 lines
3 KiB
Python
106 lines
3 KiB
Python
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}`')
|
|
|