docs: Autogenerate module option reference

Author: rvl

.gitignore

@@ -1,5 +1,6 @@
 # The output of "mkdocs build"
 /site/
+docs/reference/modules.md
 
 # Nix build results
 result*

build.nix

@@ -24,7 +24,19 @@ in {
     update-hackage = haskell.callPackage ./scripts/update-hackage.nix {};
     update-stackage = haskell.callPackage ./scripts/update-stackage.nix {};
     update-pins = haskell.callPackage ./scripts/update-pins.nix {};
-    update-docs = haskell.callPackage ./scripts/update-docs.nix {};
+    update-docs = haskell.callPackage ./scripts/update-docs.nix {
+      generatedOptions = import ./scripts/options-doc.nix {
+        # nixpkgs unstable changes "Option has no description" from an
+        # error into a warning. That is quite helpful when hardly any
+        # of our options are documented, thanks @oxij.
+        pkgs = import (pkgs.fetchFromGitHub {
+          owner = "NixOS";
+          repo = "nixpkgs";
+          rev = "4ab1c14714fc97a27655f3a6877386da3cb237bc";
+          sha256 = "16lcj9552q2jfxc27j6116qkf2vl2dcj7vhg5gdq4qi51d891yhn";
+        }) {};
+      };
+    };
     check-hydra = haskell.callPackage ./scripts/check-hydra.nix {};
   };
 }

docs/reference/modules-preamble.md

@@ -0,0 +1,10 @@
+Haskell.nix modules options for packages and components.
+
+!!! note "Undocumented"
+    Please help write me.
+
+    This documentation is generated from Nix sources in the
+    [`modules`](https://github.com/input-output-hk/haskell.nix/tree/master/modules)
+    subdirectory.
+
+    The Markdown generation script could also be improved.

docs/reference/modules.md

@@ -0,0 +1,29 @@
+{ pkgs ? import <nixpkgs> {}
+, lib ? pkgs.lib
+}:
+let
+  # Provide a dummy pkg-def for the package set function
+  pkg-def = hackage: {
+    packages = {};
+    compiler = {
+      version = "";
+      nix-name = "";
+      packages = {};
+    };
+  };
+
+  # Apply the package set function to get NixOS options.
+  inherit (import ../package-set.nix { hackage = null; inherit pkgs pkg-def; }) options;
+
+  # Use code from the NixOS manual to generate Docbook XML options list.
+  manual = import (pkgs.path + /nixos/doc/manual) {
+    inherit pkgs options;
+    config.meta.doc = [];
+    version = "testing";
+    revision = "testing";
+  };
+in
+  # Convert docbook options list to markdown
+  pkgs.runCommand "options.md" {} ''
+    ${pkgs.buildPackages.pandoc}/bin/pandoc -s -f docbook -t markdown_strict ${manual.generatedSources}/options-db.xml -o $out
+  ''

scripts/options-doc.nix

@@ -1,4 +1,5 @@
-{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs }:
+{ stdenv, writeScript, coreutils, glibc, git, openssh, gnused, mkdocs
+, generatedOptions }:
 
 with stdenv.lib;
 
@@ -15,6 +16,9 @@ in
 
     source ${./git.env}
 
+    echo "Preprocessing..."
+    cat docs/reference/modules-preamble.md ${generatedOptions} > docs/reference/modules.md
+
     echo "Building..."
     rm -rf site
     mkdocs build
@@ -23,6 +27,7 @@ in
     sed -i -e '/lastmod/d' site/sitemap.xml
     rm -f site/sitemap.xml.gz
     rev=$(git rev-parse --short HEAD)
+    rm doc/reference/modules.md
 
     echo "Updating git index..."
     git fetch origin