Improve option docs, update effect

dev/flake-module.nix

@@ -1,4 +1,4 @@
-flakeModuleArgs@{ config, lib, inputs, ... }:
+{ config, lib, inputs, ... }:
 
 {
   imports = [
@@ -28,22 +28,6 @@ flakeModuleArgs@{ config, lib, inputs, ... }:
       };
     };
 
-    packages = {
-      inherit (pkgs.nixosOptionsDoc { inherit (flakeModuleArgs) options; })
-        optionsDocBook;
-      optionsMarkdown = pkgs.runCommand "options-markdown"
-        {
-          inherit (config.packages) optionsDocBook;
-          nativeBuildInputs = [ pkgs.pandoc ];
-        } ''
-        mkdir $out
-        pandoc \
-          --from docbook \
-          --to markdown \
-          --output $out/options.md \
-          $optionsDocBook
-      '';
-    };
   };
   flake = {
     options.herculesCI = lib.mkOption { type = lib.types.raw; };
@@ -57,7 +41,7 @@ flakeModuleArgs@{ config, lib, inputs, ... }:
           in
           {
             netlifyDeploy = effects.runIf (branch == "main") (effects.netlifyDeploy {
-              content = config.flake.packages.x86_64-linux.websitePackage;
+              content = config.flake.packages.x86_64-linux.siteContent;
               secretName = "default-netlify";
               siteId = "29a153b1-3698-433c-bc73-62415efb8117";
               productionDeployment = true;

dev/flake.lock

@@ -51,15 +51,16 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1653465299,
-        "narHash": "sha256-+1jyM4dsppYFgiJf+VkAAS/l5iF0y5J7D2l1fLzT8DA=",
-        "owner": "NixOS",
+        "lastModified": 1653476104,
+        "narHash": "sha256-oVuWUnGQX+fRn/cFoNfbLEUGtsyyXuMLDQFEZ2OxP3k=",
+        "owner": "hercules-ci",
         "repo": "nixpkgs",
-        "rev": "5862243e1ab8c0a19cb448f523c27c167dcd826b",
+        "rev": "612e22e67eb6f8d5bfb6288abe515e9da3b96103",
         "type": "github"
       },
       "original": {
-        "owner": "NixOS",
+        "owner": "hercules-ci",
+        "ref": "module-docs-update",
         "repo": "nixpkgs",
         "type": "github"
       }

dev/flake.nix

@@ -4,7 +4,10 @@
   inputs = {
     # Flakes don't give us a good way to depend on .., so we don't.
     # This has drastic consequences of course.
-    nixpkgs.url = "github:NixOS/nixpkgs";
+
+    # https://github.com/NixOS/nixpkgs/pull/174460
+    # https://github.com/NixOS/nixpkgs/pull/174470
+    nixpkgs.url = "github:hercules-ci/nixpkgs/module-docs-update";
 
     pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
     pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";

site/flake-module.nix

@@ -1,22 +1,74 @@
 { ... }: {
-  perSystem = system: { config, self', inputs', pkgs, lib, ... }: {
-    packages.websitePackage = pkgs.stdenvNoCC.mkDerivation {
-      name = "site";
-      nativeBuildInputs = [ pkgs.pandoc ];
-      src = lib.cleanSourceWith {
-        filter = path: type:
-          path == ./.
-          || baseNameOf path == "index.html";
-        src = ./.;
+  perSystem = system: { config, self', inputs', pkgs, lib, ... }:
+    let
+      inherit (lib) filter any hasPrefix concatMap removePrefix;
+
+      libNix = import ../lib.nix { inherit lib; };
+      eval = libNix.evalFlakeModule { self = { }; } { };
+      opts = eval.options;
+
+      filterTransformOptions = { sourceName, sourcePath, baseUrl }:
+        let sourcePathStr = toString sourcePath;
+        in
+        opt:
+        let declarations = concatMap
+          (decl:
+            if hasPrefix sourcePathStr (toString decl)
+            then
+              let subpath = removePrefix sourcePathStr (toString decl);
+              in [{ url = baseUrl + subpath; name = sourceName + subpath; }]
+            else [ ]
+          )
+          opt.declarations;
+        in
+        if declarations == [ ]
+        then opt // { visible = false; }
+        else opt // { inherit declarations; };
+
+      optionsDoc = { sourceName, baseUrl, sourcePath, title }: pkgs.runCommand "${sourceName}-doc"
+        {
+          nativeBuildInputs = [ pkgs.libxslt.bin ];
+          inputDoc = (pkgs.nixosOptionsDoc {
+            options = opts;
+            documentType = "none";
+            transformOptions = filterTransformOptions {
+              inherit sourceName baseUrl sourcePath;
+            };
+          }).optionsDocBook;
+          inherit title;
+        } ''
+        xsltproc --stringparam title "$title" \
+          -o $out ${./options.xsl} \
+          "$inputDoc"
+      '';
+    in
+    {
+
+      packages = {
+
+        siteContent = pkgs.stdenvNoCC.mkDerivation {
+          name = "site";
+          nativeBuildInputs = [ pkgs.pandoc pkgs.libxslt.bin ];
+          src = lib.cleanSourceWith {
+            filter = path: type:
+              path == ./.
+              || baseNameOf path == "index.html";
+            src = ./.;
+          };
+          coreOptions = optionsDoc {
+            title = "Core Options";
+            sourceName = "flake-modules-core";
+            baseUrl = "https://github.com/hercules-ci/flake-modules-core/blob/main";
+            sourcePath = ../.;
+          };
+          buildPhase = ''
+            pandoc --verbose --from docbook --to html5 $coreOptions >options.html
+          '';
+          installPhase = ''
+            mkdir -p $out
+            cp *.html $out/
+          '';
+        };
       };
-      buildPhase = ''
-        pandoc --from docbook --to html5 \
-          ${config.packages.optionsDocBook} >options.html
-      '';
-      installPhase = ''
-        mkdir -p $out
-        cp *.html $out/
-      '';
     };
-  };
 }

site/options.xsl

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
+  version="1.0"
+  xmlns="http://docbook.org/ns/docbook"
+  xmlns:db="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" 
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  >
+  <xsl:template match="/">
+    <xsl:apply-templates/>
+  </xsl:template>
+  <xsl:template match="db:variablelist">
+    <chapter>
+      <title>
+        <xsl:value-of select="$title"/>
+      </title>
+      <xsl:apply-templates />
+    </chapter>
+  </xsl:template>
+  <xsl:template match="db:varlistentry">
+    <section>
+      <xsl:attribute name="xml:id">
+        <xsl:value-of select="db:term/@xml:id"/>
+      </xsl:attribute>
+      <title>
+        <xsl:copy-of select="db:term/db:option"/>
+      </title>
+      <xsl:apply-templates select="db:listitem/*"/>
+    </section>
+  </xsl:template>
+  <!-- Pandoc doesn't like block-level simplelist -->
+  <!-- https://github.com/jgm/pandoc/issues/8086 -->
+  <xsl:template match="db:simplelist">
+    <para>
+      <xsl:copy>
+        <xsl:apply-templates select="@*|node()"/>
+      </xsl:copy>
+    </para>
+  </xsl:template>
+  <!-- Turn filename tags with href attrs into explicit links -->
+  <xsl:template match="db:filename">
+    <link xlink:href="{@xlink:href}">
+      <xsl:copy>
+        <xsl:apply-templates select="@*|node()"/>
+      </xsl:copy>
+    </link>
+  </xsl:template>
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()"/>
+    </xsl:copy>
+  </xsl:template>
+</xsl:stylesheet>