BoomMicrophone/nixpkgs-suyu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #193498 from hercules-ci/nixos-doc-disambiguate-test-options

Browse source 
nixos/doc: disambiguate test option ids
This commit is contained in:
Robert Hensing 2022-10-04 21:35:49 +01:00 committed by GitHub
commit 70ec3b9f54
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 32 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
nixos/doc/manual/default.nix
View file

@ -63,6 +63,7 @@ let
};
documentType = "none";
variablelistId = "test-options-list";
optionIdPrefix = "test-opt-";
};
sources = lib.sourceFilesBySuffices ./. [".xml"];

4
nixos/doc/manual/development/running-nixos-tests-interactively.section.md
View file

@ -39,11 +39,11 @@ directory.
## Interactive-only test configuration {#sec-nixos-test-interactive-configuration}
The `.driverInteractive` attribute combines the regular test configuration with
definitions from the [`interactive` submodule](#opt-interactive). This gives you
definitions from the [`interactive` submodule](#test-opt-interactive). This gives you
a more usable, graphical, but slightly different configuration.
You can add your own interactive-only test configuration by adding extra
configuration to the [`interactive` submodule](#opt-interactive).
configuration to the [`interactive` submodule](#test-opt-interactive).
To interactively run only the regular configuration, build the `<test>.driver` attribute
instead, and call it with the flag `result/bin/nixos-test-driver --interactive`.

12
nixos/doc/manual/development/writing-nixos-tests.section.md
View file

@ -22,12 +22,12 @@ A NixOS test is a module that has the following structure:
```
We refer to the whole test above as a test module, whereas the values
in [`nodes.<name>`](#opt-nodes) are NixOS modules themselves.
in [`nodes.<name>`](#test-opt-nodes) are NixOS modules themselves.
The option [`testScript`](#opt-testScript) is a piece of Python code that executes the
The option [`testScript`](#test-opt-testScript) is a piece of Python code that executes the
test (described below). During the test, it will start one or more
virtual machines, the configuration of which is described by
the option [`nodes`](#opt-nodes).
the option [`nodes`](#test-opt-nodes).
An example of a single-node test is
[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix).
@ -171,7 +171,7 @@ The following methods are available on machine objects:
least one will be returned.
::: {.note}
This requires [`enableOCR`](#opt-enableOCR) to be set to `true`.
This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`.
:::
`get_screen_text`
@ -180,7 +180,7 @@ The following methods are available on machine objects:
machine\'s screen using optical character recognition.
::: {.note}
This requires [`enableOCR`](#opt-enableOCR) to be set to `true`.
This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`.
:::
`send_monitor_command`
@ -291,7 +291,7 @@ The following methods are available on machine objects:
`get_screen_text` and `get_screen_text_variants`).
::: {.note}
This requires [`enableOCR`](#opt-enableOCR) to be set to `true`.
This requires [`enableOCR`](#test-opt-enableOCR) to be set to `true`.
:::
`wait_for_console_text`

4
nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
View file

@ -44,14 +44,14 @@ $ ./result/bin/nixos-test-driver --keep-vm-state
<para>
The <literal>.driverInteractive</literal> attribute combines the
regular test configuration with definitions from the
<link linkend="opt-interactive"><literal>interactive</literal>
<link linkend="test-opt-interactive"><literal>interactive</literal>
submodule</link>. This gives you a more usable, graphical, but
slightly different configuration.
</para>
<para>
You can add your own interactive-only test configuration by adding
extra configuration to the
<link linkend="opt-interactive"><literal>interactive</literal>
<link linkend="test-opt-interactive"><literal>interactive</literal>
submodule</link>.
</para>
<para>

12
nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
View file

@ -24,16 +24,16 @@
<para>
We refer to the whole test above as a test module, whereas the
values in
<link linkend="opt-nodes"><literal>nodes.&lt;name&gt;</literal></link>
<link linkend="test-opt-nodes"><literal>nodes.&lt;name&gt;</literal></link>
are NixOS modules themselves.
</para>
<para>
The option
<link linkend="opt-testScript"><literal>testScript</literal></link>
<link linkend="test-opt-testScript"><literal>testScript</literal></link>
is a piece of Python code that executes the test (described below).
During the test, it will start one or more virtual machines, the
configuration of which is described by the option
<link linkend="opt-nodes"><literal>nodes</literal></link>.
<link linkend="test-opt-nodes"><literal>nodes</literal></link>.
</para>
<para>
An example of a single-node test is
@ -263,7 +263,7 @@ start_all()
<note>
<para>
This requires
<link linkend="opt-enableOCR"><literal>enableOCR</literal></link>
<link linkend="test-opt-enableOCR"><literal>enableOCR</literal></link>
to be set to <literal>true</literal>.
</para>
</note>
@ -281,7 +281,7 @@ start_all()
<note>
<para>
This requires
<link linkend="opt-enableOCR"><literal>enableOCR</literal></link>
<link linkend="test-opt-enableOCR"><literal>enableOCR</literal></link>
to be set to <literal>true</literal>.
</para>
</note>
@ -522,7 +522,7 @@ start_all()
<note>
<para>
This requires
<link linkend="opt-enableOCR"><literal>enableOCR</literal></link>
<link linkend="test-opt-enableOCR"><literal>enableOCR</literal></link>
to be set to <literal>true</literal>.
</para>
</note>

3
nixos/lib/make-options-doc/default.nix
View file

@ -26,6 +26,8 @@
# If you include more than one option list into a document, you need to
# provide different ids.
, variablelistId ? "configuration-variable-list"
# Strig to prefix to the option XML/HTML id attributes.
, optionIdPrefix ? "opt-"
, revision ? "" # Specify revision for the options
# a set of options the docs we are generating will be merged into, as if by recursiveUpdate.
# used to split the options doc build into a static part (nixos/modules) and a dynamic part
@ -183,6 +185,7 @@ in rec {
--stringparam documentType '${documentType}' \
--stringparam revision '${revision}' \
--stringparam variablelistId '${variablelistId}' \
--stringparam optionIdPrefix '${optionIdPrefix}' \
-o intermediate.xml ${./options-to-docbook.xsl} sorted.xml
${pkgs.libxslt.bin}/bin/xsltproc \
-o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml

3
nixos/lib/make-options-doc/options-to-docbook.xsl
View file

@ -15,6 +15,7 @@
<xsl:param name="documentType" />
<xsl:param name="program" />
<xsl:param name="variablelistId" />
<xsl:param name="optionIdPrefix" />
<xsl:template match="/expr/list">
@ -36,7 +37,7 @@
<xsl:attribute name="id" namespace="http://www.w3.org/XML/1998/namespace"><xsl:value-of select="$variablelistId"/></xsl:attribute>
<xsl:for-each select="attrs">
<xsl:variable name="id" select="
concat('opt-',
concat($optionIdPrefix,
translate(
attr[@name = 'name']/string/@value,
'*&lt; >[]:',

6
nixos/lib/testing/driver.nix
View file

@ -120,7 +120,7 @@ in
};
qemu.package = mkOption {
description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#opt-nodes).";
description = mdDoc "Which qemu package to use for the virtualisation of [{option}`nodes`](#test-opt-nodes).";
type = types.package;
default = hostPkgs.qemu_test;
defaultText = "hostPkgs.qemu_test";
@ -152,7 +152,7 @@ in
description = mdDoc ''
Extra arguments to pass to the test driver.
They become part of [{option}`driver`](#opt-driver) via `wrapProgram`.
They become part of [{option}`driver`](#test-opt-driver) via `wrapProgram`.
'';
type = types.listOf types.str;
default = [];
@ -172,7 +172,7 @@ in
description = mdDoc ''
Disable type checking. This must not be enabled for new NixOS tests.
This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#opt-testScript).
This may speed up your iteration cycle, unless you're working on the [{option}`testScript`](#test-opt-testScript).
'';
};
};

4
nixos/lib/testing/meta.nix
View file

@ -24,14 +24,14 @@ in
type = types.nullOr types.int;
default = null; # NOTE: null values are filtered out by `meta`.
description = mdDoc ''
The [{option}`test`](#opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds.
The [{option}`test`](#test-opt-test)'s [`meta.timeout`](https://nixos.org/manual/nixpkgs/stable/#var-meta-timeout) in seconds.
'';
};
broken = lib.mkOption {
type = types.bool;
default = false;
description = mdDoc ''
Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#opt-test) derivation.
Sets the [`meta.broken`](https://nixos.org/manual/nixpkgs/stable/#var-meta-broken) attribute on the [{option}`test`](#test-opt-test) derivation.
'';
};
};

2
nixos/lib/testing/name.nix
View file

@ -7,7 +7,7 @@ in
description = mdDoc ''
The name of the test.
This is used in the derivation names of the [{option}`driver`](#opt-driver) and [{option}`test`](#opt-test) runner.
This is used in the derivation names of the [{option}`driver`](#test-opt-driver) and [{option}`test`](#test-opt-test) runner.
'';
type = types.str;
};

8
nixos/lib/testing/nodes.nix
View file

@ -44,7 +44,7 @@ in
description = mdDoc ''
An attribute set of NixOS configuration modules.
The configurations are augmented by the [`defaults`](#opt-defaults) option.
The configurations are augmented by the [`defaults`](#test-opt-defaults) option.
They are assigned network addresses according to the `nixos/lib/testing/network.nix` module.
@ -54,7 +54,7 @@ in
defaults = mkOption {
description = mdDoc ''
NixOS configuration that is applied to all [{option}`nodes`](#opt-nodes).
NixOS configuration that is applied to all [{option}`nodes`](#test-opt-nodes).
'';
type = types.deferredModule;
default = { };
@ -62,7 +62,7 @@ in
extraBaseModules = mkOption {
description = mdDoc ''
NixOS configuration that, like [{option}`defaults`](#opt-defaults), is applied to all [{option}`nodes`](#opt-nodes) and can not be undone with [`specialisation.<name>.inheritParentConfig`](https://search.nixos.org/options?show=specialisation.%3Cname%3E.inheritParentConfig&from=0&size=50&sort=relevance&type=packages&query=specialisation).
NixOS configuration that, like [{option}`defaults`](#test-opt-defaults), is applied to all [{option}`nodes`](#test-opt-nodes) and can not be undone with [`specialisation.<name>.inheritParentConfig`](https://search.nixos.org/options?show=specialisation.%3Cname%3E.inheritParentConfig&from=0&size=50&sort=relevance&type=packages&query=specialisation).
'';
type = types.deferredModule;
default = { };
@ -82,7 +82,7 @@ in
type = types.bool;
default = false;
description = mdDoc ''
Enable to configure all [{option}`nodes`](#opt-nodes) to run with a minimal kernel.
Enable to configure all [{option}`nodes`](#test-opt-nodes) to run with a minimal kernel.
'';
};