b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #191647 from hercules-ci/nixos-options-doc-explain-migration

Browse source 
nixos/make-options-doc: Explain docbook to markdown migration
This commit is contained in:
Robert Hensing 2022-09-24 12:46:50 +01:00 committed by GitHub
parent 9c64b91d14 5b52d552cb
commit e18ab300ad
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
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: