From b928f0bc4e0aa7e99e885e930475e018e85a8841 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Tue, 9 Apr 2024 11:16:23 +0300
Subject: [PATCH] docs: extract `scrubDerivations` function from `nmd`

---
 docs/default.nix | 85 ++++++++++++++++++++++++++++++------------------
 1 file changed, 54 insertions(+), 31 deletions(-)

diff --git a/docs/default.nix b/docs/default.nix
index e67ce02..1ba0d3d 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -4,18 +4,37 @@
   lib ? import ../lib/stdlib-extended.nix pkgs.lib inputs,
   ...
 }: let
-  nmd = import inputs.nmd {
-    inherit lib;
-    # The DocBook output of `nixos-render-docs` doesn't have the change
-    # `nmd` uses to work around the broken stylesheets in
-    # `docbook-xsl-ns`, so we restore the patched version here.
-    pkgs =
-      pkgs
-      // {
-        docbook-xsl-ns =
-          pkgs.docbook-xsl-ns.override {withManOptDedupPatch = true;};
-      };
-  };
+  inherit (lib.modules) mkForce evalModules;
+  inherit (lib.strings) hasPrefix removePrefix;
+  inherit (lib.attrsets) isAttrs mapAttrs optionalAttrs recursiveUpdate isDerivation;
+
+  # From home-manager:
+  #
+  # Recursively replace each derivation in the given attribute set
+  # with the same derivation but with the `outPath` attribute set to
+  # the string `"\${pkgs.attribute.path}"`. This allows the
+  # documentation to refer to derivations through their values without
+  # establishing an actual dependency on the derivation output.
+  #
+  # This is not perfect, but it seems to cover a vast majority of use
+  # cases.
+  #
+  # Caveat: even if the package is reached by a different means, the
+  # path above will be shown and not e.g.
+  # `${config.services.foo.package}`.
+  scrubDerivations = prefixPath: attrs: let
+    scrubDerivation = name: value: let
+      pkgAttrName = prefixPath + "." + name;
+    in
+      if isAttrs value
+      then
+        scrubDerivations pkgAttrName value
+        // optionalAttrs (isDerivation value) {
+          outPath = "\${${pkgAttrName}}";
+        }
+      else value;
+  in
+    mapAttrs scrubDerivation attrs;
 
   # Make sure the used package is scrubbed to avoid actually
   # instantiating derivations.
@@ -23,30 +42,30 @@
     imports = [
       {
         _module.args = {
-          pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs);
-          pkgs_i686 = lib.mkForce {};
+          pkgs = mkForce (scrubDerivations "pkgs" pkgs);
+          pkgs_i686 = mkForce {};
         };
       }
     ];
   };
 
-  dontCheckDefinitions = {_module.check = false;};
-
-  githubDeclaration = user: repo: subpath: let
-    urlRef = "main";
-  in {
-    url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
-    name = "<${repo}/${subpath}>";
-  };
-
+  # Specify the path to the module entrypoint
   nvimPath = toString ./..;
-
   buildOptionsDocs = args @ {
     modules,
     includeModuleSystemOptions ? true,
     ...
   }: let
-    inherit ((lib.evalModules {inherit modules;})) options;
+    inherit ((evalModules {inherit modules;})) options;
+
+    # Declaration of the Github site URL.
+    githubDeclaration = user: repo: subpath: let
+      urlRef = "github.com";
+      branch = "main";
+    in {
+      url = "https://${urlRef}/${user}/${repo}/blob/${branch}/${subpath}";
+      name = "<${repo}/${subpath}>";
+    };
   in
     pkgs.buildPackages.nixosOptionsDoc ({
         options =
@@ -54,15 +73,14 @@
           then options
           else builtins.removeAttrs options ["_module"];
         transformOptions = opt:
-          opt
-          // {
-            # Clean up declaration sites to not refer to the Home Manager
+          recursiveUpdate opt {
+            # Clean up declaration sites to not refer to the neovim-flakee
             # source tree.
             declarations = map (decl:
-              if lib.hasPrefix nvimPath (toString decl)
+              if hasPrefix nvimPath (toString decl)
               then
                 githubDeclaration "notashelf" "neovim-flake"
-                (lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
+                (removePrefix "/" (removePrefix nvimPath (toString decl)))
               else if decl == "lib/modules.nix"
               then
                 # TODO: handle this in a better way (may require upstream
@@ -86,6 +104,7 @@
 
   release-config = builtins.fromJSON (builtins.readFile ../release.json);
   revision = "release-${release-config.release}";
+
   # Generate the `man home-configuration.nix` package
   nvf-configuration-manual =
     pkgs.runCommand "neovim-flake-reference-manpage" {
@@ -95,12 +114,15 @@
       # Generate manpages.
       mkdir -p $out/share/man/man5
       mkdir -p $out/share/man/man1
+
       nixos-render-docs -j $NIX_BUILD_CORES options manpage \
         --revision ${revision} \
         ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
         $out/share/man/man5/neovim-flake.5
+
       cp ${./neovim-flake.1} $out/share/man/man1/neovim-flake.1
     '';
+
   # Generate the HTML manual pages
   neovim-flake-manual = pkgs.callPackage ./manual.nix {
     inherit (inputs) nmd;
@@ -110,6 +132,7 @@
       neovim-flake = nvimModuleDocs.optionsJSON;
     };
   };
+
   html = neovim-flake-manual;
   htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {} {inherit html;};
 in {
@@ -120,7 +143,7 @@ in {
     # `nixosOptionsDoc` is more customizable.
     json =
       pkgs.runCommand "options.json" {
-        meta.description = "List of Home Manager options in JSON format";
+        meta.description = "List of neovim-flake options in JSON format";
       } ''
         mkdir -p $out/{share/doc,nix-support}
         cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake