alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

nixos/make-options-doc: Explain docbook to markdown migration

Browse source
This commit is contained in:
Robert Hensing 2022-09-17 13:38:23 +01:00
parent 8ad3fe7279
commit 5b52d552cb
1 changed files with 18 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
nixos/lib/make-options-doc/mergeJSON.py
View file

@ -259,20 +259,24 @@ def is_docbook(o, key):
# check that every option has a description
hasWarnings = False
hasErrors = False
hasDocBookErrors = False
for (k, v) in options.items():
if errorOnDocbook:
if isinstance(v.value.get('description', {}), str):
hasErrors = True
hasDocBookErrors = True
print(
f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",
file=sys.stderr)
elif is_docbook(v.value, 'defaultText'):
hasErrors = True
hasDocBookErrors = True
print(
f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",
file=sys.stderr)
elif is_docbook(v.value, 'example'):
hasErrors = True
hasDocBookErrors = True
print(
f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",
file=sys.stderr)
@ -287,6 +291,20 @@ for (k, v) in options.items():
f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +
"https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)
if hasDocBookErrors:
print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +
"NixOS is in the process of migrating from DocBook to Markdown, and " +
"DocBook is disallowed for in-tree modules. To change your contribution to "+
"use Markdown, apply mdDoc and literalMD. For example:\n" +
"\n" +
" example.foo = mkOption {\n" +
" description = lib.mdDoc ''your description'';\n" +
" defaultText = lib.literalMD ''your description of default'';\n" +
" }\n" +
"\n" +
" example.enable = mkEnableOption (lib.mdDoc ''your thing'');",
file = sys.stderr)
if hasErrors:
sys.exit(1)
if hasWarnings and warningsAreErrors: