From 301824d21698e21025b6136e66833fe3e5b18655 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 function reference docs

Add a `treefmt.functionsDoc` passthru, which is included on the treefmt
section of the nixpkgs manual.

This generates reference docs for functions defined in
`pkgs/by-name/tr/treefmt/lib.nix`, using `nixdoc`.
---
 doc/doc-support/package.nix               |  2 ++
 doc/packages/treefmt.section.md           |  6 +++++-
 doc/redirects.json                        | 12 ++++++++++++
 pkgs/by-name/tr/treefmt/functions-doc.nix | 19 +++++++++++++++++++
 pkgs/by-name/tr/treefmt/package.nix       |  3 +++
 5 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 pkgs/by-name/tr/treefmt/functions-doc.nix

diff --git a/doc/doc-support/package.nix b/doc/doc-support/package.nix
index db8066c8dc56..89e03240cee9 100644
--- a/doc/doc-support/package.nix
+++ b/doc/doc-support/package.nix
@@ -14,6 +14,7 @@
   nixpkgs ? { },
   markdown-code-runner,
   roboto,
+  treefmt,
 }:
 
 stdenvNoCC.mkDerivation (
@@ -47,6 +48,7 @@ stdenvNoCC.mkDerivation (
 
     postPatch = ''
       ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
+      ln -s ${treefmt.functionsDoc.markdown} ./packages/treefmt-functions.section.md
     '';
 
     buildPhase = ''
diff --git a/doc/packages/treefmt.section.md b/doc/packages/treefmt.section.md
index aaf0ac69346b..873f93ecd657 100644
--- a/doc/packages/treefmt.section.md
+++ b/doc/packages/treefmt.section.md
@@ -3,6 +3,10 @@
 [treefmt](https://github.com/numtide/treefmt) streamlines the process of applying formatters to your project, making it a breeze with just one command line.
 
 The [`treefmt` package](https://search.nixos.org/packages?channel=unstable&show=treefmt)
-provides functions for configuring treefmt using the module system.
+provides functions for configuring treefmt using the module system, which are [documented below](#sec-functions-library-treefmt).
 
 Alternatively, treefmt can be configured using [treefmt-nix](https://github.com/numtide/treefmt-nix).
+
+```{=include=} sections auto-id-prefix=auto-generated-treefmt-functions
+treefmt-functions.section.md
+```
diff --git a/doc/redirects.json b/doc/redirects.json
index 362d0a197689..30239175f49a 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -72,6 +72,15 @@
   "part-toolchains": [
     "index.html#part-toolchains"
   ],
+  "pkgs.treefmt.buildConfig": [
+    "index.html#pkgs.treefmt.buildConfig"
+  ],
+  "pkgs.treefmt.evalConfig": [
+    "index.html#pkgs.treefmt.evalConfig"
+  ],
+  "pkgs.treefmt.withConfig": [
+    "index.html#pkgs.treefmt.withConfig"
+  ],
   "preface": [
     "index.html#preface"
   ],
@@ -111,6 +120,9 @@
   "sec-building-packages-with-llvm-using-clang-stdenv": [
     "index.html#sec-building-packages-with-llvm-using-clang-stdenv"
   ],
+  "sec-functions-library-treefmt": [
+    "index.html#sec-functions-library-treefmt"
+  ],
   "sec-inkscape": [
     "index.html#sec-inkscape"
   ],
diff --git a/pkgs/by-name/tr/treefmt/functions-doc.nix b/pkgs/by-name/tr/treefmt/functions-doc.nix
new file mode 100644
index 000000000000..df67d902aba4
--- /dev/null
+++ b/pkgs/by-name/tr/treefmt/functions-doc.nix
@@ -0,0 +1,19 @@
+{
+  nixdoc,
+  runCommand,
+}:
+{
+  markdown =
+    runCommand "treefmt-functions-doc"
+      {
+        nativeBuildInputs = [ nixdoc ];
+      }
+      ''
+        nixdoc --file ${./lib.nix} \
+          --description "Functions Reference" \
+          --prefix "pkgs" \
+          --category "treefmt" \
+          --anchor-prefix "" \
+           > $out
+      '';
+}
diff --git a/pkgs/by-name/tr/treefmt/package.nix b/pkgs/by-name/tr/treefmt/package.nix
index 1a4873157f0c..08ca96eced1f 100644
--- a/pkgs/by-name/tr/treefmt/package.nix
+++ b/pkgs/by-name/tr/treefmt/package.nix
@@ -36,6 +36,9 @@ buildGoModule rec {
       ;
 
     tests = callPackages ./tests.nix { };
+
+    # Documentation for functions defined in `./lib.nix`
+    functionsDoc = callPackages ./functions-doc.nix { };
   };
 
   meta = {