nixos/doc: Wire up the test options reference

nixos/doc/manual/default.nix

@@ -38,6 +38,33 @@ let
     };
   };
 
+  nixos-lib = import ../../lib { };
+
+  testOptionsDoc = let
+      eval = nixos-lib.evalTest {
+        # Avoid evaluating a NixOS config prototype.
+        config.node.type = lib.types.deferredModule;
+        options._module.args = lib.mkOption { internal = true; };
+      };
+    in buildPackages.nixosOptionsDoc {
+      inherit (eval) options;
+      inherit (revision);
+      transformOptions = opt: opt // {
+        # Clean up declaration sites to not refer to the NixOS source tree.
+        declarations =
+          map
+            (decl:
+              if hasPrefix (toString ../../..) (toString decl)
+              then
+                let subpath = removePrefix "/" (removePrefix (toString ../../..) (toString decl));
+                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
+              else decl)
+            opt.declarations;
+      };
+      documentType = "none";
+      variablelistId = "test-options-list";
+    };
+
   sources = lib.sourceFilesBySuffices ./. [".xml"];
 
   modulesDoc = builtins.toFile "modules.xml" ''
@@ -52,6 +79,7 @@ let
     mkdir $out
     ln -s ${modulesDoc} $out/modules.xml
     ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml
+    ln -s ${testOptionsDoc.optionsDocBook} $out/test-options-db.xml
     printf "%s" "${version}" > $out/version
   '';
 

nixos/doc/manual/development/writing-nixos-tests.section.md

@@ -52,7 +52,6 @@ Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://
 ```
 
 Overrides can be added by defining an anonymous module in `all-tests.nix`.
-For the purpose of constructing a test matrix, use the `matrix` options instead.
 
 ```nix
   hostname = runTest { imports = [ ./hostname.nix ]; defaults.networking.firewall.enable = false; };
@@ -476,3 +475,11 @@ added using the parameter `extraPythonPackages`. For example, you could add
 ```
 
 In that case, `numpy` is chosen from the generic `python3Packages`.
+
+## Test Options Reference {#sec-test-options-reference}
+
+The following options can be used when writing tests.
+
+```{=docbook}
+<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>
+```

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

@@ -1,4 +1,4 @@
-<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-nixos-tests">
+<section xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-nixos-tests">
   <title>Writing Tests</title>
   <para>
     A NixOS test is a module that has the following structure:
@@ -67,9 +67,7 @@
 </programlisting>
       <para>
         Overrides can be added by defining an anonymous module in
-        <literal>all-tests.nix</literal>. For the purpose of
-        constructing a test matrix, use the <literal>matrix</literal>
-        options instead.
+        <literal>all-tests.nix</literal>.
       </para>
       <programlisting language="bash">
   hostname = runTest { imports = [ ./hostname.nix ]; defaults.networking.firewall.enable = false; };
@@ -770,4 +768,11 @@ def foo_running():
       <literal>python3Packages</literal>.
     </para>
   </section>
+  <section xml:id="sec-test-options-reference">
+    <title>Test Options Reference</title>
+    <para>
+      The following options can be used when writing tests.
+    </para>
+    <xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/>
+  </section>
 </section>