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

lib/options: deprecate docbook text and literalDocBook

Browse Source 
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:
pennae 2022-09-01 19:23:59 +02:00 committed by pennae
parent 8c309aa43a
commit 767485a0de
9 changed files with 118 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
lib/options.nix
View File

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

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

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

19
nixos/doc/manual/development/option-declarations.section.md
View File

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

26
nixos/doc/manual/from_md/development/option-declarations.section.xml
View File

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

19
nixos/doc/manual/from_md/release-notes/rl-2211.section.xml
View File

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

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

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

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

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

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

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

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

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