colin/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

nixos/documentation: deprecate docbook option docs

Browse Source 
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.
This commit is contained in:
pennae 2023-01-15 14:56:46 +01:00 committed by pennae
parent 45a5c01a26
commit df09c21fb2
7 changed files with 66 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
nixos/doc/manual/default.nix
View File

@ -209,7 +209,7 @@ let
in rec {
inherit generatedSources;
inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;
inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;
# Generate the NixOS manual.
manualHTML = runCommand "nixos-manual-html"

16
nixos/doc/manual/from_md/release-notes/rl-2305.section.xml
View File

@ -416,6 +416,22 @@
sudo and sources the environment variables.
</para>
</listitem>
<listitem>
<para>
DocBook option documentation, which has been deprecated since
22.11, will now cause a warning when documentation is built.
Out-of-tree modules should migrate to using CommonMark
documentation as outlined in
<xref linkend="sec-option-declarations" /> to silence this
warning.
</para>
<para>
DocBook option documentation support will be removed in the
next release and CommonMark will become the default. DocBook
option documentation that has not been migrated until then
will no longer render properly or cause errors.
</para>
</listitem>
<listitem>
<para>
The <literal>dnsmasq</literal> service now takes configuration

4
nixos/doc/manual/release-notes/rl-2305.section.md
View File

@ -101,6 +101,10 @@ In addition to numerous new and upgraded packages, this release has the followin
- `services.mastodon` gained a tootctl wrapped named `mastodon-tootctl` similar to `nextcloud-occ` which can be executed from any user and switches to the configured mastodon user with sudo and sources the environment variables.
- DocBook option documentation, which has been deprecated since 22.11, will now cause a warning when documentation is built. Out-of-tree modules should migrate to using CommonMark documentation as outlined in [](#sec-option-declarations) to silence this warning.
DocBook option documentation support will be removed in the next release and CommonMark will become the default. DocBook option documentation that has not been migrated until then will no longer render properly or cause errors.
- The `dnsmasq` service now takes configuration via the
`services.dnsmasq.settings` attribute set. The option
`services.dnsmasq.extraConfig` will be deprecated when NixOS 22.11 reaches

11
nixos/lib/make-options-doc/default.nix
View File

@ -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

40
nixos/lib/make-options-doc/mergeJSON.py
View File

@ -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)

2
nixos/lib/testing/testScript.nix
View File

@ -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.
'';

8
nixos/modules/misc/documentation.nix
View File

@ -357,6 +357,14 @@ in
(mkIf cfg.nixos.enable {
system.build.manual = manual;
system.activationScripts.check-manual-docbook = ''
if [[ $(cat ${manual.optionsUsedDocbook}) = 1 ]]; then
echo -e "\e[31;1mwarning\e[0m: This configuration contains option documentation in docbook." \
"Support for docbook is deprecated and will be removed after NixOS 23.05." \
"See nix-store --read-log ${builtins.unsafeDiscardStringContext manual.optionsJSON.drvPath}"
fi
'';
environment.systemPackages = []
++ optional cfg.man.enable manual.manpages
++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ];