nixosTest: Simplify doc by deprecating syntax sugar

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

···
 ```nix
 import ./make-test-python.nix {
 
-  # Either the configuration of a single machine:
-  machine =
-    { config, pkgs, ... }:
-    { configuration…
-    };
-
-  # Or a set of machines:
+  # One or more machines:
   nodes =
-    { machine1 =
+    { machine =
         { config, pkgs, ... }: { … };
       machine2 =
         { config, pkgs, ... }: { … };
···
 
 The attribute `testScript` is a bit 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
-attribute `machine` (if you need only one machine in your test) or by
-the attribute `nodes` (if you need multiple machines). For instance,
-[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix)
-only needs a single machine to test whether users can log in
+virtual machines, the configuration of which is described by
+the attribute `nodes`.
+
+An example of a single-node test is
+[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix).
+It only needs a single machine to test whether users can log in
 on the virtual console, whether device ownership is correctly maintained
-when switching between consoles, and so on. On the other hand,
-[`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix),
-which tests NFS client and server functionality in the
-Linux kernel (including whether locks are maintained across server
-crashes), requires three machines: a server and two clients.
+when switching between consoles, and so on. An interesting multi-node test is
+[`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix).
+It uses two client nodes to test correct locking across server crashes.
 
 There are a few special NixOS configuration options for test VMs:
 
···
 actions, such as starting VMs, executing commands in the VMs, and so on.
 Each virtual machine is represented as an object stored in the variable
 `name` if this is also the identifier of the machine in the declarative
-config. If you didn\'t specify multiple machines using the `nodes`
-attribute, it is just `machine`. The following example starts the
+config. If you specified a node `nodes.machine`, the following example starts the
 machine, waits until it has finished booting, then executes a command
 and checks that the output is more-or-less correct:
 
···
   raise Exception("Wrong OS")
 ```
 
-The first line is actually unnecessary; machines are implicitly started
+The first line is technically unnecessary; machines are implicitly started
 when you first execute an action on them (such as `wait_for_unit` or
 `succeed`). If you have multiple machines, you can speed up the test by
 starting them in parallel:
···
 ```nix
 import ./make-test-python.nix {
   skipLint = true;
-  machine =
+  nodes.machine =
     { config, pkgs, ... }:
     { configuration…
     };

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

···
   <programlisting language="bash">
 import ./make-test-python.nix {
 
-  # Either the configuration of a single machine:
-  machine =
-    { config, pkgs, ... }:
-    { configuration…
-    };
-
-  # Or a set of machines:
+  # One or more machines:
   nodes =
-    { machine1 =
+    { machine =
         { config, pkgs, ... }: { … };
       machine2 =
         { config, pkgs, ... }: { … };
···
     The attribute <literal>testScript</literal> is a bit 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 attribute <literal>machine</literal> (if you need
-    only one machine in your test) or by the attribute
-    <literal>nodes</literal> (if you need multiple machines). For
-    instance,
-    <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>
-    only needs a single machine to test whether users can log in on the
-    virtual console, whether device ownership is correctly maintained
-    when switching between consoles, and so on. On the other hand,
-    <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>,
-    which tests NFS client and server functionality in the Linux kernel
-    (including whether locks are maintained across server crashes),
-    requires three machines: a server and two clients.
+    described by the attribute <literal>nodes</literal>.
+  </para>
+  <para>
+    An example of a single-node test is
+    <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>.
+    It only needs a single machine to test whether users can log in on
+    the virtual console, whether device ownership is correctly
+    maintained when switching between consoles, and so on. An
+    interesting multi-node test is
+    <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>.
+    It uses two client nodes to test correct locking across server
+    crashes.
   </para>
   <para>
     There are a few special NixOS configuration options for test VMs:
···
     various actions, such as starting VMs, executing commands in the
     VMs, and so on. Each virtual machine is represented as an object
     stored in the variable <literal>name</literal> if this is also the
-    identifier of the machine in the declarative config. If you didn't
-    specify multiple machines using the <literal>nodes</literal>
-    attribute, it is just <literal>machine</literal>. The following
+    identifier of the machine in the declarative config. If you
+    specified a node <literal>nodes.machine</literal>, the following
     example starts the machine, waits until it has finished booting,
     then executes a command and checks that the output is more-or-less
     correct:
···
   raise Exception(&quot;Wrong OS&quot;)
 </programlisting>
   <para>
-    The first line is actually unnecessary; machines are implicitly
+    The first line is technically unnecessary; machines are implicitly
     started when you first execute an action on them (such as
     <literal>wait_for_unit</literal> or <literal>succeed</literal>). If
     you have multiple machines, you can speed up the test by starting
···
     <programlisting language="bash">
 import ./make-test-python.nix {
   skipLint = true;
-  machine =
+  nodes.machine =
     { config, pkgs, ... }:
     { configuration…
     };

nixos/lib/testing-python.nix

···
             )];
           };
         in
+          lib.warnIf (t?machine) "In test `${name}': The `machine' attribute in NixOS tests (pkgs.nixosTest / make-test-pyton.nix / testing-python.nix / makeTest) is deprecated. Please use the equivalent `nodes.machine'."
           build-vms.buildVirtualNetwork (
               nodes // lib.optionalAttrs (machine != null) { inherit machine; }
           );