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

nixos/doc: disambiguate test option ids

nixos/doc/manual/default.nix

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

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

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`

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>

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>

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

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; >[]:',

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).
       '';
     };
   };

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.
             '';
           };
         };

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

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.
       '';
     };