From 96f041725f6e92f7159b6d2913f07c18101d92dc Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Wed, 14 May 2025 07:20:21 +0100
Subject: [PATCH] doc/packages/treefmt: add location to function reference docs

Get the function's source code location using `unsafeGetAttrPos` and
pass that to `nixdoc` so that links to definitions are included in the
docs.
---
 pkgs/by-name/tr/treefmt/functions-doc.nix | 38 +++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/pkgs/by-name/tr/treefmt/functions-doc.nix b/pkgs/by-name/tr/treefmt/functions-doc.nix
index df67d902aba4..86dc23b226ea 100644
--- a/pkgs/by-name/tr/treefmt/functions-doc.nix
+++ b/pkgs/by-name/tr/treefmt/functions-doc.nix
@@ -1,8 +1,45 @@
 {
+  lib,
+  writers,
   nixdoc,
   runCommand,
+  treefmt,
 }:
+let
+  root = toString ./.;
+  revision = lib.trivial.revisionWithDefault "master";
+  removeRoot = file: lib.removePrefix "/" (lib.removePrefix root file);
+
+  # Import and apply `./lib.nix`, which contains treefmt's public functions
+  #
+  # NOTE: we cannot access them via `treefmt.passthru` or `callPackages ./lib.nix { }`,
+  # because that would be opaque to `unsafeGetAttrPos`.
+  attrs =
+    let
+      fn = import ./lib.nix;
+      args = builtins.mapAttrs (_: _: null) (builtins.functionArgs fn);
+    in
+    fn args;
+in
 {
+  locations = lib.pipe attrs [
+    builtins.attrNames
+    (builtins.map (
+      name:
+      let
+        pos = builtins.unsafeGetAttrPos name attrs;
+        file = removeRoot pos.file;
+        line = toString pos.line;
+        subpath = "pkgs/by-name/tr/treefmt/${file}";
+        url = "https://github.com/NixOS/nixpkgs/blob/${revision}/${subpath}#L${line}";
+      in
+      assert lib.hasPrefix root pos.file;
+      lib.nameValuePair "pkgs.treefmt.${name}" "[${subpath}:${line}](${url}) in `<nixpkgs>`"
+    ))
+    builtins.listToAttrs
+    (writers.writeJSON "treefmt-function-locations")
+  ];
+
   markdown =
     runCommand "treefmt-functions-doc"
       {
@@ -10,6 +47,7 @@
       }
       ''
         nixdoc --file ${./lib.nix} \
+          --locs ${treefmt.functionsDoc.locations} \
           --description "Functions Reference" \
           --prefix "pkgs" \
           --category "treefmt" \