docs: use MarkDown for option docs

flake.nix

@@ -2,6 +2,10 @@
   description = "A complete and Simple Nixos Mailserver";
 
   inputs = {
+    flake-compat = {
+      url = "github:edolstra/flake-compat";
+      flake = false;
+    };
     utils.url = "github:numtide/flake-utils";
     nixpkgs.url = "flake:nixpkgs/nixos-unstable";
     nixpkgs-22_11.url = "flake:nixpkgs/nixos-22.11";
@@ -11,7 +15,8 @@
     };
   };
 
-  outputs = { self, utils, blobs, nixpkgs, nixpkgs-22_11 }: let
+  outputs = { self, utils, blobs, nixpkgs, nixpkgs-22_11, ... }: let
+    lib = nixpkgs.lib;
     system = "x86_64-linux";
     pkgs = nixpkgs.legacyPackages.${system};
     releases = [
@@ -43,22 +48,18 @@
     #   external-21_05 = <derivation>;
     #   ...
     # }
-    allTests = pkgs.lib.listToAttrs (
-      pkgs.lib.flatten (map (t: map (r: genTest t r) releases) testNames));
+    allTests = lib.listToAttrs (
+      lib.flatten (map (t: map (r: genTest t r) releases) testNames));
 
     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;
+    # Generate a MarkDown file describing the options of the NixOS mailserver module
+    optionsDoc = let
+      eval = lib.evalModules {
         modules = [
           mailserverModule
           {
-            # Because the blockbook package is currently broken (we
-            # don't care about this package but it is part of the
-            # NixOS module evaluation)
-            nixpkgs.config.allowBroken = true;
+            _module.check = false;
             mailserver = {
               fqdn = "mx.example.com";
               domains = [
@@ -71,27 +72,26 @@
             };
           }
         ];
-
       };
-      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
+      options = builtins.toFile "options.json" (builtins.toJSON
+        (lib.filter (opt: opt.visible && !opt.internal && lib.head opt.loc == "mailserver")
+          (lib.optionAttrSetToDocList eval.options)));
+    in pkgs.runCommand "options.md" { buildInputs = [pkgs.python3Minimal]; } ''
+      echo "Generating options.md from ${options}"
+      python ${./scripts/generate-options.py} ${options} > $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
+    generateOptions = pkgs.writeShellScriptBin "generate-options" ''
+      install -vm644 ${optionsDoc} ./docs/options.md
     '';
 
-    # 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}
+    # This is to ensure we don't forget to update the options.md file
+    testOptions = pkgs.runCommand "test-options" {} ''
+      if ! diff -q ${./docs/options.md} ${optionsDoc}
       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"
+        echo "The file ./docs/options.md is not up-to-date and needs to be regenerated!"
+        echo "  hint: run 'nix-shell --run generate-options' to generate this file"
         exit 1
       fi
       echo "test: ok" > $out
@@ -99,43 +99,43 @@
 
     documentation = pkgs.stdenv.mkDerivation {
       name = "documentation";
-      src = pkgs.lib.sourceByRegex ./docs ["logo.png" "conf.py" "Makefile" ".*rst$"];
+      src = lib.sourceByRegex ./docs ["logo\\.png" "conf\\.py" "Makefile" ".*\\.rst"];
       buildInputs = [(
-        pkgs.python3.withPackages(p: [
-          p.sphinx
-          p.sphinx_rtd_theme
+        pkgs.python3.withPackages (p: with p; [
+          sphinx
+          sphinx_rtd_theme
+          myst-parser
         ])
       )];
       buildPhase = ''
-        cp ${generateRstOptions} options.rst
-        mkdir -p _static
+        cp ${optionsDoc} options.md
         # Workaround for https://github.com/sphinx-doc/sphinx/issues/3451
-        export SOURCE_DATE_EPOCH=$(${pkgs.coreutils}/bin/date +%s)
+        unset SOURCE_DATE_EPOCH
         make html
       '';
       installPhase = ''
-        cp -r _build/html $out
+        cp -Tr _build/html $out
       '';
     };
 
-  in rec {
-    nixosModules.mailserver = mailserverModule ;
-    nixosModule = self.nixosModules.mailserver;
+  in {
+    nixosModules = rec {
+      mailserver = mailserverModule;
+      default = mailserver;
+    };
+    nixosModule = self.nixosModules.default; # compatibility
     hydraJobs.${system} = allTests // {
-      test-rst-options = testRstOptions;
+      test-options = testOptions;
       inherit documentation;
     };
     checks.${system} = allTests;
-    devShell.${system} = pkgs.mkShell {
-      buildInputs = with pkgs; [
-        generateRstOptionsScript
-        (python3.withPackages (p: with p; [
-          sphinx
-          sphinx_rtd_theme
-        ]))
-        jq
+    devShells.${system}.default = pkgs.mkShell {
+      inputsFrom = [ documentation ];
+      packages = with pkgs; [
+        generateOptions
         clamav
       ];
     };
+    devShell.${system} = self.devShells.${system}.default; # compatibility
   };
 }