pyrox.dev
1import collections
2import json
3import os
4import sys
5from typing import Any, Dict, List
6
7JSON = Dict[str, Any]
8
9class Key:
10 def __init__(self, path: List[str]):
11 self.path = path
12 def __hash__(self):
13 result = 0
14 for id in self.path:
15 result ^= hash(id)
16 return result
17 def __eq__(self, other):
18 return type(self) is type(other) and self.path == other.path
19
20Option = collections.namedtuple('Option', ['name', 'value'])
21
22# pivot a dict of options keyed by their display name to a dict keyed by their path
23def pivot(options: Dict[str, JSON]) -> Dict[Key, Option]:
24 result: Dict[Key, Option] = dict()
25 for (name, opt) in options.items():
26 result[Key(opt['loc'])] = Option(name, opt)
27 return result
28
29# pivot back to indexed-by-full-name
30# like the docbook build we'll just fail if multiple options with differing locs
31# render to the same option name.
32def unpivot(options: Dict[Key, Option]) -> Dict[str, JSON]:
33 result: Dict[str, Dict] = dict()
34 for (key, opt) in options.items():
35 if opt.name in result:
36 raise RuntimeError(
37 'multiple options with colliding ids found',
38 opt.name,
39 result[opt.name]['loc'],
40 opt.value['loc'],
41 )
42 result[opt.name] = opt.value
43 return result
44
45warningsAreErrors = False
46warnOnDocbook = False
47errorOnDocbook = False
48optOffset = 0
49for arg in sys.argv[1:]:
50 if arg == "--warnings-are-errors":
51 optOffset += 1
52 warningsAreErrors = True
53 if arg == "--warn-on-docbook":
54 optOffset += 1
55 warnOnDocbook = True
56 elif arg == "--error-on-docbook":
57 optOffset += 1
58 errorOnDocbook = True
59
60options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))
61overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
62
63# fix up declaration paths in lazy options, since we don't eval them from a full nixpkgs dir
64for (k, v) in options.items():
65 # The _module options are not declared in nixos/modules
66 if v.value['loc'][0] != "_module":
67 v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}' if isinstance(s, str) else s, v.value['declarations']))
68
69# merge both descriptions
70for (k, v) in overrides.items():
71 cur = options.setdefault(k, v).value
72 for (ok, ov) in v.value.items():
73 if ok == 'declarations':
74 decls = cur[ok]
75 for d in ov:
76 if d not in decls:
77 decls += [d]
78 elif ok == "type":
79 # ignore types of placeholder options
80 if ov != "_unspecified" or cur[ok] == "_unspecified":
81 cur[ok] = ov
82 elif ov is not None or cur.get(ok, None) is None:
83 cur[ok] = ov
84
85severity = "error" if warningsAreErrors else "warning"
86
87def is_docbook(o, key):
88 val = o.get(key, {})
89 if not isinstance(val, dict):
90 return False
91 return val.get('_type', '') == 'literalDocBook'
92
93# check that every option has a description
94hasWarnings = False
95hasErrors = False
96hasDocBook = False
97for (k, v) in options.items():
98 if warnOnDocbook or errorOnDocbook:
99 kind = "error" if errorOnDocbook else "warning"
100 if isinstance(v.value.get('description', {}), str):
101 hasErrors |= errorOnDocbook
102 hasDocBook = True
103 print(
104 f"\x1b[1;31m{kind}: option {v.name} description uses DocBook\x1b[0m",
105 file=sys.stderr)
106 elif is_docbook(v.value, 'defaultText'):
107 hasErrors |= errorOnDocbook
108 hasDocBook = True
109 print(
110 f"\x1b[1;31m{kind}: option {v.name} default uses DocBook\x1b[0m",
111 file=sys.stderr)
112 elif is_docbook(v.value, 'example'):
113 hasErrors |= errorOnDocbook
114 hasDocBook = True
115 print(
116 f"\x1b[1;31m{kind}: option {v.name} example uses DocBook\x1b[0m",
117 file=sys.stderr)
118
119 if v.value.get('description', None) is None:
120 hasWarnings = True
121 print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)
122 v.value['description'] = "This option has no description."
123 if v.value.get('type', "unspecified") == "unspecified":
124 hasWarnings = True
125 print(
126 f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +
127 "https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)
128
129if hasDocBook:
130 (why, what) = (
131 ("disallowed for in-tree modules", "contribution") if errorOnDocbook
132 else ("deprecated for option documentation", "module")
133 )
134 print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +
135 "NixOS is in the process of migrating from DocBook to Markdown, and " +
136 f"DocBook is {why}. To change your {what} to "+
137 "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " +
138 "functions where they are available. For example:\n" +
139 "\n" +
140 " example.foo = mkOption {\n" +
141 " description = lib.mdDoc ''your description'';\n" +
142 " defaultText = lib.literalMD ''your description of default'';\n" +
143 " };\n" +
144 "\n" +
145 " example.enable = mkEnableOption (lib.mdDoc ''your thing'');\n" +
146 " example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +
147 " imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",
148 file = sys.stderr)
149 with open(os.getenv('TOUCH_IF_DB'), 'x'):
150 # just make sure it exists
151 pass
152
153if hasErrors:
154 sys.exit(1)
155if hasWarnings and warningsAreErrors:
156 print(
157 "\x1b[1;31m" +
158 "Treating warnings as errors. Set documentation.nixos.options.warningsAreErrors " +
159 "to false to ignore these warnings." +
160 "\x1b[0m",
161 file=sys.stderr)
162 sys.exit(1)
163
164json.dump(unpivot(options), fp=sys.stdout)