diff options
author | pennae <github@quasiparticle.net> | 2023-01-15 14:56:46 +0100 |
---|---|---|
committer | pennae <82953136+pennae@users.noreply.github.com> | 2023-01-22 17:08:40 +0100 |
commit | df09c21fb262ed07f01099625ef9310a8a8392ae (patch) | |
tree | e2ae96e7be4140d239ca410d1cc39efcb4b0f095 /nixos/lib | |
parent | 45a5c01a26e8fc5752a2bc969977ffc5e9cadac6 (diff) |
nixos/documentation: deprecate docbook option docs
following the plan in https://github.com/NixOS/nixpkgs/pull/189318#discussion_r961764451 also adds an activation script to print the warning during activation instead of during build, otherwise folks using the new CLI that hides build logs by default might never see the warning.
Diffstat (limited to 'nixos/lib')
-rw-r--r-- | nixos/lib/make-options-doc/default.nix | 11 | ||||
-rw-r--r-- | nixos/lib/make-options-doc/mergeJSON.py | 40 | ||||
-rw-r--r-- | nixos/lib/testing/testScript.nix | 2 |
3 files changed, 37 insertions, 16 deletions
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index e2ed7bb71885b..7595b66771a58 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -139,9 +139,10 @@ in rec { dst=$out/share/doc/nixos mkdir -p $dst + TOUCH_IF_DB=$dst/.used-docbook \ python ${./mergeJSON.py} \ ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \ - ${lib.optionalString (! allowDocBook) "--error-on-docbook"} \ + ${if allowDocBook then "--warn-on-docbook" else "--error-on-docbook"} \ ${lib.optionalString markdownByDefault "--markdown-by-default"} \ $baseJSON $options \ > $dst/options.json @@ -153,6 +154,14 @@ in rec { echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products ''; + optionsUsedDocbook = pkgs.runCommand "options-used-docbook" {} '' + if [ -e ${optionsJSON}/share/doc/nixos/.used-docbook ]; then + echo 1 + else + echo 0 + fi >"$out" + ''; + # Convert options.json into an XML file. # The actual generation of the xml file is done in nix purely for the convenience # of not having to generate the xml some other way diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index c4f490fc2ad87..3108b9e2197fa 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -228,6 +228,7 @@ def convertMD(options: Dict[str, Any]) -> str: return options warningsAreErrors = False +warnOnDocbook = False errorOnDocbook = False markdownByDefault = False optOffset = 0 @@ -235,7 +236,10 @@ for arg in sys.argv[1:]: if arg == "--warnings-are-errors": optOffset += 1 warningsAreErrors = True - if arg == "--error-on-docbook": + if arg == "--warn-on-docbook": + optOffset += 1 + warnOnDocbook = True + elif arg == "--error-on-docbook": optOffset += 1 errorOnDocbook = True if arg == "--markdown-by-default": @@ -278,26 +282,27 @@ def is_docbook(o, key): # check that every option has a description hasWarnings = False hasErrors = False -hasDocBookErrors = False +hasDocBook = False for (k, v) in options.items(): - if errorOnDocbook: + if warnOnDocbook or errorOnDocbook: + kind = "error" if errorOnDocbook else "warning" if isinstance(v.value.get('description', {}), str): - hasErrors = True - hasDocBookErrors = True + hasErrors |= errorOnDocbook + hasDocBook = True print( - f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m", + f"\x1b[1;31m{kind}: option {v.name} description uses DocBook\x1b[0m", file=sys.stderr) elif is_docbook(v.value, 'defaultText'): - hasErrors = True - hasDocBookErrors = True + hasErrors |= errorOnDocbook + hasDocBook = True print( - f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m", + f"\x1b[1;31m{kind}: option {v.name} default uses DocBook\x1b[0m", file=sys.stderr) elif is_docbook(v.value, 'example'): - hasErrors = True - hasDocBookErrors = True + hasErrors |= errorOnDocbook + hasDocBook = True print( - f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m", + f"\x1b[1;31m{kind}: option {v.name} example uses DocBook\x1b[0m", file=sys.stderr) if v.value.get('description', None) is None: @@ -310,10 +315,14 @@ 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: +if hasDocBook: + (why, what) = ( + ("disallowed for in-tree modules", "contribution") if errorOnDocbook + else ("deprecated for option documentation", "module") + ) 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 "+ + f"DocBook is {why}. To change your {what} to "+ "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " + "functions where they are available. For example:\n" + "\n" + @@ -326,6 +335,9 @@ if hasDocBookErrors: " example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" + " imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];", file = sys.stderr) + with open(os.getenv('TOUCH_IF_DB'), 'x'): + # just make sure it exists + pass if hasErrors: sys.exit(1) diff --git a/nixos/lib/testing/testScript.nix b/nixos/lib/testing/testScript.nix index 5d4181c5f5dd5..5c36d754d79d7 100644 --- a/nixos/lib/testing/testScript.nix +++ b/nixos/lib/testing/testScript.nix @@ -7,7 +7,7 @@ in options = { testScript = mkOption { type = either str (functionTo str); - description = '' + description = mdDoc '' A series of python declarations and statements that you write to perform the test. ''; |