summaryrefslogtreecommitdiffstats
path: root/nixos
diff options
context:
space:
mode:
authorRobert Hensing <roberth@users.noreply.github.com>2022-10-04 21:35:49 +0100
committerGitHub <noreply@github.com>2022-10-04 21:35:49 +0100
commit70ec3b9f545e9c681e5dfcac10fcde3c4ff1eb87 (patch)
tree008711d472cd6362e7faf49feb48f30edc6ebfc4 /nixos
parent603bdef4c7b21a5ae9f23f63950e95c177ff18b5 (diff)
parent216c5dc10dd9d842909fe256567e9aeda3212396 (diff)
Merge pull request #193498 from hercules-ci/nixos-doc-disambiguate-test-options
nixos/doc: disambiguate test option ids
Diffstat (limited to 'nixos')
-rw-r--r--nixos/doc/manual/default.nix1
-rw-r--r--nixos/doc/manual/development/running-nixos-tests-interactively.section.md4
-rw-r--r--nixos/doc/manual/development/writing-nixos-tests.section.md12
-rw-r--r--nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml4
-rw-r--r--nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml12
-rw-r--r--nixos/lib/make-options-doc/default.nix3
-rw-r--r--nixos/lib/make-options-doc/options-to-docbook.xsl3
-rw-r--r--nixos/lib/testing/driver.nix6
-rw-r--r--nixos/lib/testing/meta.nix4
-rw-r--r--nixos/lib/testing/name.nix2
-rw-r--r--nixos/lib/testing/nodes.nix8
11 files changed, 32 insertions, 27 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index ecd62eb4e848..6db20cdd6418 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -63,6 +63,7 @@ let
};
documentType = "none";
variablelistId = "test-options-list";
+ optionIdPrefix = "test-opt-";
};
sources = lib.sourceFilesBySuffices ./. [".xml"];
diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
index d9c316f4b139..1130672cb376 100644
--- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
+++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md
@@ -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`.
diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md
index 99704ec3c141..2efe52b9883c 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.section.md
+++ b/nixos/doc/manual/development/writing-nixos-tests.section.md
@@ -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`
diff --git a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
index 35d9bbd1c1fe..16db709f8b91 100644
--- a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
+++ b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml
@@ -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>
diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
index 32f5fdb77f50..4db196273dad 100644
--- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
+++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
@@ -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>
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index 43dbff0e68dd..6a1bb868c20d 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -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
diff --git a/nixos/lib/make-options-doc/options-to-docbook.xsl b/nixos/lib/make-options-doc/options-to-docbook.xsl
index 978d5e2468a8..d5b921b1dedb 100644
--- a/nixos/lib/make-options-doc/options-to-docbook.xsl
+++ b/nixos/lib/make-options-doc/options-to-docbook.xsl
@@ -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; >[]:',
diff --git a/nixos/lib/testing/driver.nix b/nixos/lib/testing/driver.nix
index 04e99f9e21d6..fb181c1d7e9a 100644
--- a/nixos/lib/testing/driver.nix
+++ b/nixos/lib/testing/driver.nix
@@ -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).
'';
};
};
diff --git a/nixos/lib/testing/meta.nix b/nixos/lib/testing/meta.nix
index 4d8b0e0f1c43..65754fe3c541 100644
--- a/nixos/lib/testing/meta.nix
+++ b/nixos/lib/testing/meta.nix
@@ -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.
'';
};
};
diff --git a/nixos/lib/testing/name.nix b/nixos/lib/testing/name.nix
index a54622e139bf..0af593169eec 100644
--- a/nixos/lib/testing/name.nix
+++ b/nixos/lib/testing/name.nix
@@ -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;
};
diff --git a/nixos/lib/testing/nodes.nix b/nixos/lib/testing/nodes.nix
index 765af2878dfe..0395238cbaae 100644
--- a/nixos/lib/testing/nodes.nix
+++ b/nixos/lib/testing/nodes.nix
@@ -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.
'';
};