Merge pull request #204996 from sandydoo/improve/render-nix-types-in-commonmark
nixos/make-options-doc: pretty-print literals
This commit is contained in:
commit
edc730d7c2
|
@ -111,14 +111,16 @@ in rec {
|
||||||
inherit optionsNix;
|
inherit optionsNix;
|
||||||
|
|
||||||
optionsAsciiDoc = pkgs.runCommand "options.adoc" {} ''
|
optionsAsciiDoc = pkgs.runCommand "options.adoc" {} ''
|
||||||
${pkgs.python3Minimal}/bin/python ${./generateAsciiDoc.py} \
|
${pkgs.python3Minimal}/bin/python ${./generateDoc.py} \
|
||||||
< ${optionsJSON}/share/doc/nixos/options.json \
|
--format asciidoc \
|
||||||
|
${optionsJSON}/share/doc/nixos/options.json \
|
||||||
> $out
|
> $out
|
||||||
'';
|
'';
|
||||||
|
|
||||||
optionsCommonMark = pkgs.runCommand "options.md" {} ''
|
optionsCommonMark = pkgs.runCommand "options.md" {} ''
|
||||||
${pkgs.python3Minimal}/bin/python ${./generateCommonMark.py} \
|
${pkgs.python3Minimal}/bin/python ${./generateDoc.py} \
|
||||||
< ${optionsJSON}/share/doc/nixos/options.json \
|
--format commonmark \
|
||||||
|
${optionsJSON}/share/doc/nixos/options.json \
|
||||||
> $out
|
> $out
|
||||||
'';
|
'';
|
||||||
|
|
||||||
|
|
|
@ -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()
|
|
|
@ -1,27 +0,0 @@
|
||||||
import json
|
|
||||||
import sys
|
|
||||||
|
|
||||||
options = json.load(sys.stdin)
|
|
||||||
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()
|
|
108
nixos/lib/make-options-doc/generateDoc.py
Normal file
108
nixos/lib/make-options-doc/generateDoc.py
Normal file
|
@ -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('<', '<').replace('>', '>'))
|
||||||
|
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}`')
|
||||||
|
|
Loading…
Reference in a new issue