lib/options: deprecate docbook text and literalDocBook
deprecate literalDocBook by adding a warning (that will not fire yet) to its uses and other docbook literal strings by adding optional warning message to mergeJSON.
This commit is contained in:
parent
8c309aa43a
commit
767485a0de
|
@ -284,7 +284,10 @@ rec {
|
||||||
*/
|
*/
|
||||||
literalDocBook = text:
|
literalDocBook = text:
|
||||||
if ! isString text then throw "literalDocBook expects a string."
|
if ! isString text then throw "literalDocBook expects a string."
|
||||||
else { _type = "literalDocBook"; inherit text; };
|
else
|
||||||
|
lib.warnIf (lib.isInOldestRelease 2211)
|
||||||
|
"literalDocBook is deprecated, use literalMD instead"
|
||||||
|
{ _type = "literalDocBook"; inherit text; };
|
||||||
|
|
||||||
/* Transition marker for documentation that's already migrated to markdown
|
/* Transition marker for documentation that's already migrated to markdown
|
||||||
syntax.
|
syntax.
|
||||||
|
|
|
@ -6,6 +6,7 @@
|
||||||
, extraSources ? []
|
, extraSources ? []
|
||||||
, baseOptionsJSON ? null
|
, baseOptionsJSON ? null
|
||||||
, warningsAreErrors ? true
|
, warningsAreErrors ? true
|
||||||
|
, allowDocBook ? true
|
||||||
, prefix ? ../../..
|
, prefix ? ../../..
|
||||||
}:
|
}:
|
||||||
|
|
||||||
|
@ -28,7 +29,7 @@ let
|
||||||
stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;
|
stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;
|
||||||
|
|
||||||
optionsDoc = buildPackages.nixosOptionsDoc {
|
optionsDoc = buildPackages.nixosOptionsDoc {
|
||||||
inherit options revision baseOptionsJSON warningsAreErrors;
|
inherit options revision baseOptionsJSON warningsAreErrors allowDocBook;
|
||||||
transformOptions = opt: opt // {
|
transformOptions = opt: opt // {
|
||||||
# Clean up declaration sites to not refer to the NixOS source tree.
|
# Clean up declaration sites to not refer to the NixOS source tree.
|
||||||
declarations = map stripAnyPrefixes opt.declarations;
|
declarations = map stripAnyPrefixes opt.declarations;
|
||||||
|
|
|
@ -44,26 +44,23 @@ The function `mkOption` accepts the following arguments.
|
||||||
: A textual representation of the default value to be rendered verbatim in
|
: A textual representation of the default value to be rendered verbatim in
|
||||||
the manual. Useful if the default value is a complex expression or depends
|
the manual. Useful if the default value is a complex expression or depends
|
||||||
on other values or packages.
|
on other values or packages.
|
||||||
Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
|
Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
|
||||||
a plain English description in DocBook format.
|
a plain English description in [Nixpkgs-flavored Markdown](
|
||||||
|
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.
|
||||||
|
|
||||||
`example`
|
`example`
|
||||||
|
|
||||||
: An example value that will be shown in the NixOS manual.
|
: An example value that will be shown in the NixOS manual.
|
||||||
You can use `lib.literalExpression` and `lib.literalDocBook` in the same way
|
You can use `lib.literalExpression` and `lib.literalMD` in the same way
|
||||||
as in `defaultText`.
|
as in `defaultText`.
|
||||||
|
|
||||||
`description`
|
`description`
|
||||||
|
|
||||||
: A textual description of the option, in DocBook format, that will be
|
: A textual description of the option, in [Nixpkgs-flavored Markdown](
|
||||||
|
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
|
||||||
included in the NixOS manual. During the migration process from DocBook
|
included in the NixOS manual. During the migration process from DocBook
|
||||||
to CommonMark the description may also be written in CommonMark, but has
|
to CommonMark the description may also be written in DocBook, but this is
|
||||||
to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See
|
discouraged.
|
||||||
the nixpkgs manual for [the list of CommonMark extensions](
|
|
||||||
https://nixos.org/nixpkgs/manual/#sec-contributing-markup)
|
|
||||||
supported by NixOS documentation.
|
|
||||||
|
|
||||||
New documentation should preferably be written as CommonMark.
|
|
||||||
|
|
||||||
## Utility functions for common option patterns {#sec-option-declarations-util}
|
## Utility functions for common option patterns {#sec-option-declarations-util}
|
||||||
|
|
||||||
|
|
|
@ -69,8 +69,10 @@ options = {
|
||||||
verbatim in the manual. Useful if the default value is a
|
verbatim in the manual. Useful if the default value is a
|
||||||
complex expression or depends on other values or packages. Use
|
complex expression or depends on other values or packages. Use
|
||||||
<literal>lib.literalExpression</literal> for a Nix expression,
|
<literal>lib.literalExpression</literal> for a Nix expression,
|
||||||
<literal>lib.literalDocBook</literal> for a plain English
|
<literal>lib.literalMD</literal> for a plain English
|
||||||
description in DocBook format.
|
description in
|
||||||
|
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
|
||||||
|
Markdown</link> format.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -82,7 +84,7 @@ options = {
|
||||||
<para>
|
<para>
|
||||||
An example value that will be shown in the NixOS manual. You
|
An example value that will be shown in the NixOS manual. You
|
||||||
can use <literal>lib.literalExpression</literal> and
|
can use <literal>lib.literalExpression</literal> and
|
||||||
<literal>lib.literalDocBook</literal> in the same way as in
|
<literal>lib.literalMD</literal> in the same way as in
|
||||||
<literal>defaultText</literal>.
|
<literal>defaultText</literal>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -93,18 +95,12 @@ options = {
|
||||||
</term>
|
</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
A textual description of the option, in DocBook format, that
|
A textual description of the option, in
|
||||||
will be included in the NixOS manual. During the migration
|
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
|
||||||
process from DocBook to CommonMark the description may also be
|
Markdown</link> format, that will be included in the NixOS
|
||||||
written in CommonMark, but has to be wrapped in
|
manual. During the migration process from DocBook to
|
||||||
<literal>lib.mdDoc</literal> to differentiate it from DocBook.
|
CommonMark the description may also be written in DocBook, but
|
||||||
See the nixpkgs manual for
|
this is discouraged.
|
||||||
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">the
|
|
||||||
list of CommonMark extensions</link> supported by NixOS
|
|
||||||
documentation.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
New documentation should preferably be written as CommonMark.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
|
@ -577,6 +577,25 @@
|
||||||
as coreboot’s fork is no longer available.
|
as coreboot’s fork is no longer available.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Option descriptions, examples, and defaults writting in
|
||||||
|
DocBook are now deprecated. Using CommonMark is preferred and
|
||||||
|
will become the default in a future release.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The
|
||||||
|
<literal>documentation.nixos.options.allowDocBook</literal>
|
||||||
|
option was added to ease the transition to CommonMark option
|
||||||
|
documentation. Setting this option to <literal>false</literal>
|
||||||
|
causes an error for every option included in the manual that
|
||||||
|
uses DocBook documentation; it defaults to
|
||||||
|
<literal>true</literal> to preserve the previous behavior and
|
||||||
|
will be removed once the transition to CommonMark is complete.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The udisks2 service, available at
|
The udisks2 service, available at
|
||||||
|
|
|
@ -197,6 +197,10 @@ Use `configure.packages` instead.
|
||||||
|
|
||||||
- memtest86+ was updated from 5.00-coreboot-002 to 6.00-beta2. It is now the upstream version from https://www.memtest.org/, as coreboot's fork is no longer available.
|
- memtest86+ was updated from 5.00-coreboot-002 to 6.00-beta2. It is now the upstream version from https://www.memtest.org/, as coreboot's fork is no longer available.
|
||||||
|
|
||||||
|
- Option descriptions, examples, and defaults writting in DocBook are now deprecated. Using CommonMark is preferred and will become the default in a future release.
|
||||||
|
|
||||||
|
- The `documentation.nixos.options.allowDocBook` option was added to ease the transition to CommonMark option documentation. Setting this option to `false` causes an error for every option included in the manual that uses DocBook documentation; it defaults to `true` to preserve the previous behavior and will be removed once the transition to CommonMark is complete.
|
||||||
|
|
||||||
- The udisks2 service, available at `services.udisks2.enable`, is now disabled by default. It will automatically be enabled through services and desktop environments as needed.
|
- The udisks2 service, available at `services.udisks2.enable`, is now disabled by default. It will automatically be enabled through services and desktop environments as needed.
|
||||||
This also means that polkit will now actually be disabled by default. The default for `security.polkit.enable` was already flipped in the previous release, but udisks2 being enabled by default re-enabled it.
|
This also means that polkit will now actually be disabled by default. The default for `security.polkit.enable` was already flipped in the previous release, but udisks2 being enabled by default re-enabled it.
|
||||||
|
|
||||||
|
|
|
@ -34,6 +34,10 @@
|
||||||
# instead of printing warnings for eg options with missing descriptions (which may be lost
|
# instead of printing warnings for eg options with missing descriptions (which may be lost
|
||||||
# by nix build unless -L is given), emit errors instead and fail the build
|
# by nix build unless -L is given), emit errors instead and fail the build
|
||||||
, warningsAreErrors ? true
|
, warningsAreErrors ? true
|
||||||
|
# allow docbook option docs if `true`. only markdown documentation is allowed when set to
|
||||||
|
# `false`, and a different renderer may be used with different bugs and performance
|
||||||
|
# characteristics but (hopefully) indistinguishable output.
|
||||||
|
, allowDocBook ? true
|
||||||
}:
|
}:
|
||||||
|
|
||||||
let
|
let
|
||||||
|
@ -127,26 +131,23 @@ in rec {
|
||||||
];
|
];
|
||||||
options = builtins.toFile "options.json"
|
options = builtins.toFile "options.json"
|
||||||
(builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));
|
(builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));
|
||||||
|
# merge with an empty set if baseOptionsJSON is null to run markdown
|
||||||
|
# processing on the input options
|
||||||
|
baseJSON =
|
||||||
|
if baseOptionsJSON == null
|
||||||
|
then builtins.toFile "base.json" "{}"
|
||||||
|
else baseOptionsJSON;
|
||||||
}
|
}
|
||||||
''
|
''
|
||||||
# Export list of options in different format.
|
# Export list of options in different format.
|
||||||
dst=$out/share/doc/nixos
|
dst=$out/share/doc/nixos
|
||||||
mkdir -p $dst
|
mkdir -p $dst
|
||||||
|
|
||||||
${
|
|
||||||
if baseOptionsJSON == null
|
|
||||||
then ''
|
|
||||||
# `cp $options $dst/options.json`, but with temporary
|
|
||||||
# markdown processing
|
|
||||||
python ${./mergeJSON.py} $options <(echo '{}') > $dst/options.json
|
|
||||||
''
|
|
||||||
else ''
|
|
||||||
python ${./mergeJSON.py} \
|
python ${./mergeJSON.py} \
|
||||||
${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
|
${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
|
||||||
${baseOptionsJSON} $options \
|
${lib.optionalString (! allowDocBook) "--error-on-docbook"} \
|
||||||
|
$baseJSON $options \
|
||||||
> $dst/options.json
|
> $dst/options.json
|
||||||
''
|
|
||||||
}
|
|
||||||
|
|
||||||
brotli -9 < $dst/options.json > $dst/options.json.br
|
brotli -9 < $dst/options.json > $dst/options.json.br
|
||||||
|
|
||||||
|
|
|
@ -212,8 +212,17 @@ def convertMD(options: Dict[str, Any]) -> str:
|
||||||
|
|
||||||
return options
|
return options
|
||||||
|
|
||||||
warningsAreErrors = sys.argv[1] == "--warnings-are-errors"
|
warningsAreErrors = False
|
||||||
optOffset = 1 if warningsAreErrors else 0
|
errorOnDocbook = False
|
||||||
|
optOffset = 0
|
||||||
|
for arg in sys.argv[1:]:
|
||||||
|
if arg == "--warnings-are-errors":
|
||||||
|
optOffset += 1
|
||||||
|
warningsAreErrors = True
|
||||||
|
if arg == "--error-on-docbook":
|
||||||
|
optOffset += 1
|
||||||
|
errorOnDocbook = True
|
||||||
|
|
||||||
options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))
|
options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))
|
||||||
overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
|
overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
|
||||||
|
|
||||||
|
@ -241,9 +250,33 @@ for (k, v) in overrides.items():
|
||||||
|
|
||||||
severity = "error" if warningsAreErrors else "warning"
|
severity = "error" if warningsAreErrors else "warning"
|
||||||
|
|
||||||
|
def is_docbook(o, key):
|
||||||
|
val = o.get(key, {})
|
||||||
|
if not isinstance(val, dict):
|
||||||
|
return False
|
||||||
|
return val.get('_type', '') == 'literalDocBook'
|
||||||
|
|
||||||
# check that every option has a description
|
# check that every option has a description
|
||||||
hasWarnings = False
|
hasWarnings = False
|
||||||
|
hasErrors = False
|
||||||
for (k, v) in options.items():
|
for (k, v) in options.items():
|
||||||
|
if errorOnDocbook:
|
||||||
|
if isinstance(v.value.get('description', {}), str):
|
||||||
|
hasErrors = 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
|
||||||
|
print(
|
||||||
|
f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",
|
||||||
|
file=sys.stderr)
|
||||||
|
elif is_docbook(v.value, 'example'):
|
||||||
|
hasErrors = True
|
||||||
|
print(
|
||||||
|
f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",
|
||||||
|
file=sys.stderr)
|
||||||
|
|
||||||
if v.value.get('description', None) is None:
|
if v.value.get('description', None) is None:
|
||||||
hasWarnings = True
|
hasWarnings = True
|
||||||
print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)
|
print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)
|
||||||
|
@ -254,6 +287,8 @@ for (k, v) in options.items():
|
||||||
f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +
|
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)
|
"https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)
|
||||||
|
|
||||||
|
if hasErrors:
|
||||||
|
sys.exit(1)
|
||||||
if hasWarnings and warningsAreErrors:
|
if hasWarnings and warningsAreErrors:
|
||||||
print(
|
print(
|
||||||
"\x1b[1;31m" +
|
"\x1b[1;31m" +
|
||||||
|
|
|
@ -99,7 +99,7 @@ let
|
||||||
exit 1
|
exit 1
|
||||||
} >&2
|
} >&2
|
||||||
'';
|
'';
|
||||||
inherit (cfg.nixos.options) warningsAreErrors;
|
inherit (cfg.nixos.options) warningsAreErrors allowDocBook;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
|
@ -255,6 +255,23 @@ in
|
||||||
'';
|
'';
|
||||||
};
|
};
|
||||||
|
|
||||||
|
nixos.options.allowDocBook = mkOption {
|
||||||
|
type = types.bool;
|
||||||
|
default = true;
|
||||||
|
description = lib.mdDoc ''
|
||||||
|
Whether to allow DocBook option docs. When set to `false` all option using
|
||||||
|
DocBook documentation will cause a manual build error; additionally a new
|
||||||
|
renderer may be used.
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
The `false` setting for this option is not yet fully supported. While it
|
||||||
|
should work fine and produce the same output as the previous toolchain
|
||||||
|
using DocBook it may not work in all circumstances. Whether markdown option
|
||||||
|
documentation is allowed is independent of this option.
|
||||||
|
:::
|
||||||
|
'';
|
||||||
|
};
|
||||||
|
|
||||||
nixos.options.warningsAreErrors = mkOption {
|
nixos.options.warningsAreErrors = mkOption {
|
||||||
type = types.bool;
|
type = types.bool;
|
||||||
default = true;
|
default = true;
|
||||||
|
|
Loading…
Reference in a new issue