pyrox.dev
Merge pull request #191647 from hercules-ci/nixos-options-doc-explain-migration
nixos/make-options-doc: Explain docbook to markdown migration
authored by Robert Hensing and committed by GitHub e18ab300 9c64b91d
+18
nixos/lib/make-options-doc/mergeJSON.py
+18
nixos/lib/make-options-doc/mergeJSON.py
···
259
# check that every option has a description
260
hasWarnings = False
261
hasErrors = False
262
for (k, v) in options.items():
263
if errorOnDocbook:
264
if isinstance(v.value.get('description', {}), str):
265
hasErrors = True
266
print(
267
f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",
268
file=sys.stderr)
269
elif is_docbook(v.value, 'defaultText'):
270
hasErrors = True
271
print(
272
f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",
273
file=sys.stderr)
274
elif is_docbook(v.value, 'example'):
275
hasErrors = True
276
print(
277
f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",
278
file=sys.stderr)
···
286
print(
287
f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +
288
"https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)
289
290
if hasErrors:
291
sys.exit(1)
···
259
# check that every option has a description
260
hasWarnings = False
261
hasErrors = False
262
+
hasDocBookErrors = False
263
for (k, v) in options.items():
264
if errorOnDocbook:
265
if isinstance(v.value.get('description', {}), str):
266
hasErrors = True
267
+
hasDocBookErrors = True
268
print(
269
f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",
270
file=sys.stderr)
271
elif is_docbook(v.value, 'defaultText'):
272
hasErrors = True
273
+
hasDocBookErrors = True
274
print(
275
f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",
276
file=sys.stderr)
277
elif is_docbook(v.value, 'example'):
278
hasErrors = True
279
+
hasDocBookErrors = True
280
print(
281
f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",
282
file=sys.stderr)
···
290
print(
291
f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +
292
"https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)
293
+
294
+
if hasDocBookErrors:
295
+
print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +
296
+
"NixOS is in the process of migrating from DocBook to Markdown, and " +
297
+
"DocBook is disallowed for in-tree modules. To change your contribution to "+
298
+
"use Markdown, apply mdDoc and literalMD. For example:\n" +
299
+
"\n" +
300
+
" example.foo = mkOption {\n" +
301
+
" description = lib.mdDoc ''your description'';\n" +
302
+
" defaultText = lib.literalMD ''your description of default'';\n" +
303
+
" }\n" +
304
+
"\n" +
305
+
" example.enable = mkEnableOption (lib.mdDoc ''your thing'');",
306
+
file = sys.stderr)
307
308
if hasErrors:
309
sys.exit(1)