docs: generate the list of options

To generate the list of options, we need to generate and commit a rst
file to make all files available for ReadTheDoc.

An Hydra test ensures this generated file is up-to-date. If it is not
up-to-date, the error message explains the user how to generate it:
the user just needs to run `nix-shell --run generate-rst-options`.

flake.nix

@@ -47,13 +47,53 @@
     allTests = pkgs.lib.listToAttrs (
       pkgs.lib.flatten (map (t: map (r: genTest t r) releases) testNames));
 
-  in {
-    nixosModules.mailserver = import ./.;
+    mailserverModule = import ./.;
+
+    # Generate a rst file describing options of the NixOS mailserver module 
+    generateRstOptions = let
+      eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
+        inherit system;
+        modules = [
+          mailserverModule
+          {
+            mailserver.fqdn = "mx.example.com";
+          }
+        ];
+        
+      };
+      options = pkgs.nixosOptionsDoc {
+        options = eval.options;
+      };
+    in pkgs.runCommand "options.rst" { buildInputs = [pkgs.python3]; } ''
+      echo Generating options.rst from ${options.optionsJSON}/share/doc/nixos/options.json
+      python ${./scripts/generate-rst-options.py} ${options.optionsJSON}/share/doc/nixos/options.json > $out
+    '';
+
+    # This is a script helping users to generate this file in the docs directory
+    generateRstOptionsScript = pkgs.writeScriptBin "generate-rst-options" ''
+      cp -v ${generateRstOptions} ./docs/options.rst
+    '';
+
+    # This is to ensure we don't forget to update the options.rst file
+    testRstOptions = pkgs.runCommand "test-rst-options" {} ''
+      if ! diff -q ${./docs/options.rst} ${generateRstOptions}
+      then
+        echo "The file ./docs/options.rst is not up-to-date and needs to be regenerated!"
+        echo "  hint: run 'nix-shell --run generate-rst-options' to generate this file"
+      fi
+      echo "test: ok" > $out
+    '';
+
+  in rec {
+    nixosModules.mailserver = mailserverModule ;
     nixosModule = self.nixosModules.mailserver;
-    hydraJobs.${system} = allTests;
+    hydraJobs.${system} = allTests // {
+      test-rst-options = testRstOptions;
+    };
     checks.${system} = allTests;
     devShell.${system} = pkgs.mkShell {
       buildInputs = with pkgs; [
+        generateRstOptionsScript
         (python3.withPackages (p: with p; [
           sphinx
           sphinx_rtd_theme