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

docs/howto-develop.rst

@@ -46,6 +46,13 @@ documentation:
    $ make html
    $ firefox ./_build/html/index.html
 
+Note if you modify some NixOS mailserver options, you would also need
+to regenerate the ``options.rst`` file:
+
+::
+
+   $ nix-shell --run generate-rst-options
+
 Nixops
 ------
 

docs/index.rst

@@ -17,6 +17,7 @@ Welcome to NixOS Mailserver's documentation!
    howto-develop
    faq
    release-notes
+   options
 
 .. toctree::
    :maxdepth: 1

flake.nix

@@ -47,13 +47,53 @@
     allTests = pkgs.lib.listToAttrs (
       pkgs.lib.flatten (map (t: map (r: genTest t r) releases) testNames));
 
-  in {
+    mailserverModule = import ./.;
-    nixosModules.mailserver = 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

scripts/generate-rst-options.py

@@ -0,0 +1,64 @@
+import json
+import sys
+
+header = """
+Mailserver Options
+==================
+
+mailserver
+~~~~~~~~~~
+
+"""
+
+template = """
+{key}
+{line}
+
+{description}
+
+{type}
+{default}
+"""
+
+f = open(sys.argv[1])
+options = json.load(f)
+
+options = { k: v for k, v in options.items() if k.startswith("mailserver.") }
+
+groups = [ "mailserver.loginAccount",
+           "mailserver.certificate",
+           "mailserver.dkim",
+           "mailserver.fullTextSearch",
+           "mailserver.redis",
+           "mailserver.monitoring",
+           "mailserver.backup",
+           "mailserver.borg" ]
+
+def print_option(name, value):
+    if 'default' in v:
+        if v['default'] == "":
+            default = '- Default: ``""``'
+        else:
+            default = '- Default: ``{}``'.format(v['default'])
+    else:
+        default = ""
+    print(template.format(
+        key=k,
+        line="-"*len(k),
+        description=v['description'],
+        type="- Type: ``{}``".format(v['type']),
+        default=default))
+
+print(header)
+for k, v in options.items():
+    if any([k.startswith(c) for c in groups]):
+        continue
+    print_option(k, v)
+
+for c in groups:
+    print(c)
+    print("~"*len(c))
+    print()
+    for k, v in options.items():
+        if k.startswith(c):
+            print_option(k, v)