diff options
author | Robert Hensing <robert@roberthensing.nl> | 2022-09-17 13:38:23 +0100 |
---|---|---|
committer | Robert Hensing <robert@roberthensing.nl> | 2022-09-17 13:38:23 +0100 |
commit | 5b52d552cb3c4f162bc2783aea5d1730c94b7033 (patch) | |
tree | ca1ac9917aadcb3730e25626fa50782ab41eb9e3 /nixos | |
parent | 8ad3fe72798c08457ccd061d36373aa6178b2c1c (diff) |
nixos/make-options-doc: Explain docbook to markdown migration
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/lib/make-options-doc/mergeJSON.py | 18 |
1 files changed, 18 insertions, 0 deletions
diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index eae9ca0312446..8a8498746bf6c 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -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: |