mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-10-31 14:41:27 +00:00
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:
|
||||
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
|
||||
syntax.
|
||||
|
@ -6,6 +6,7 @@
|
||||
, extraSources ? []
|
||||
, baseOptionsJSON ? null
|
||||
, warningsAreErrors ? true
|
||||
, allowDocBook ? true
|
||||
, prefix ? ../../..
|
||||
}:
|
||||
|
||||
@ -28,7 +29,7 @@ let
|
||||
stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;
|
||||
|
||||
optionsDoc = buildPackages.nixosOptionsDoc {
|
||||
inherit options revision baseOptionsJSON warningsAreErrors;
|
||||
inherit options revision baseOptionsJSON warningsAreErrors allowDocBook;
|
||||
transformOptions = opt: opt // {
|
||||
# Clean up declaration sites to not refer to the NixOS source tree.
|
||||
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
|
||||
the manual. Useful if the default value is a complex expression or depends
|
||||
on other values or packages.
|
||||
Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
|
||||
a plain English description in DocBook format.
|
||||
Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
|
||||
a plain English description in [Nixpkgs-flavored Markdown](
|
||||
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.
|
||||
|
||||
`example`
|
||||
|
||||
: 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`.
|
||||
|
||||
`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
|
||||
to CommonMark the description may also be written in CommonMark, but has
|
||||
to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See
|
||||
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.
|
||||
to CommonMark the description may also be written in DocBook, but this is
|
||||
discouraged.
|
||||
|
||||
## 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
|
||||
complex expression or depends on other values or packages. Use
|
||||
<literal>lib.literalExpression</literal> for a Nix expression,
|
||||
<literal>lib.literalDocBook</literal> for a plain English
|
||||
description in DocBook format.
|
||||
<literal>lib.literalMD</literal> for a plain English
|
||||
description in
|
||||
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
|
||||
Markdown</link> format.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -82,7 +84,7 @@ options = {
|
||||
<para>
|
||||
An example value that will be shown in the NixOS manual. You
|
||||
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>.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -93,18 +95,12 @@ options = {
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A textual description of the option, in DocBook format, that
|
||||
will be included in the NixOS manual. During the migration
|
||||
process from DocBook to CommonMark the description may also be
|
||||
written in CommonMark, but has to be wrapped in
|
||||
<literal>lib.mdDoc</literal> to differentiate it from DocBook.
|
||||
See the nixpkgs manual for
|
||||
<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.
|
||||
A textual description of the option, in
|
||||
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
|
||||
Markdown</link> format, that will be included in the NixOS
|
||||
manual. During the migration process from DocBook to
|
||||
CommonMark the description may also be written in DocBook, but
|
||||
this is discouraged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -577,6 +577,25 @@
|
||||
as coreboot’s fork is no longer available.
|
||||
</para>
|
||||
</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>
|
||||
<para>
|
||||
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.
|
||||
|
||||
- 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.
|
||||
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
|
||||
# by nix build unless -L is given), emit errors instead and fail the build
|
||||
, 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
|
||||
@ -127,26 +131,23 @@ in rec {
|
||||
];
|
||||
options = builtins.toFile "options.json"
|
||||
(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.
|
||||
dst=$out/share/doc/nixos
|
||||
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} \
|
||||
${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
|
||||
${baseOptionsJSON} $options \
|
||||
> $dst/options.json
|
||||
''
|
||||
}
|
||||
python ${./mergeJSON.py} \
|
||||
${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
|
||||
${lib.optionalString (! allowDocBook) "--error-on-docbook"} \
|
||||
$baseJSON $options \
|
||||
> $dst/options.json
|
||||
|
||||
brotli -9 < $dst/options.json > $dst/options.json.br
|
||||
|
||||
|
@ -212,8 +212,17 @@ def convertMD(options: Dict[str, Any]) -> str:
|
||||
|
||||
return options
|
||||
|
||||
warningsAreErrors = sys.argv[1] == "--warnings-are-errors"
|
||||
optOffset = 1 if warningsAreErrors else 0
|
||||
warningsAreErrors = False
|
||||
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')))
|
||||
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"
|
||||
|
||||
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
|
||||
hasWarnings = False
|
||||
hasErrors = False
|
||||
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:
|
||||
hasWarnings = True
|
||||
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 " +
|
||||
"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:
|
||||
print(
|
||||
"\x1b[1;31m" +
|
||||
|
@ -99,7 +99,7 @@ let
|
||||
exit 1
|
||||
} >&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 {
|
||||
type = types.bool;
|
||||
default = true;
|
||||
|
Loading…
Reference in New Issue
Block a user