doc/packages/treefmt: add option reference docs

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

This generates reference docs for options declared in
`treefmt.evalConfig`.

Author: MattSturgeon

doc/doc-support/package.nix

@@ -49,6 +49,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
+      ln -s ${treefmt.optionsDoc.optionsJSON}/share/doc/nixos/options.json ./treefmt-options.json
     '';
 
     buildPhase = ''

doc/packages/treefmt.section.md

@@ -3,10 +3,21 @@
 [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, which are [documented below](#sec-functions-library-treefmt).
+provides functions for configuring treefmt using the module system, which are [documented below](#sec-functions-library-treefmt), along with [their options](#sec-treefmt-options-reference).
 
 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
 ```
+
+## Options Reference {#sec-treefmt-options-reference}
+
+The following attributes can be passed to [`withConfig`](#pkgs.treefmt.withConfig) or [`evalConfig`](#pkgs.treefmt.evalConfig):
+
+```{=include=} options
+id-prefix: opt-treefmt-
+list-id: configuration-variable-list
+source: ../treefmt-options.json
+```
+

doc/redirects.json

@@ -420,6 +420,9 @@
   "sec-tools-of-stdenv": [
     "index.html#sec-tools-of-stdenv"
   ],
+  "sec-treefmt-options-reference": [
+    "index.html#sec-treefmt-options-reference"
+  ],
   "ssec-cosmic-common-issues": [
     "index.html#ssec-cosmic-common-issues"
   ],

pkgs/by-name/tr/treefmt/lib.nix

@@ -15,11 +15,9 @@
 
     # Inputs
 
-    `module`
-    : A treefmt module, configuring options that include:
-      - `name`: `String` (default `"treefmt-with-config"`)
-      - `settings`: `Module` (default `{ }`)
-      - `runtimeInputs`: `[Derivation]` (default `[ ]`)
+    : A treefmt module. See [options reference].
+
+    [options reference]: https://nixos.org/manual/nixpkgs/unstable#sec-treefmt-options-reference
   */
   evalConfig =
     module:
@@ -51,11 +49,9 @@
 
     # Inputs
 
-    `module`
-    : A treefmt module, configuring options that include:
-      - `name`: `String` (default `"treefmt-with-config"`)
-      - `settings`: `Module` (default `{ }`)
-      - `runtimeInputs`: `[Derivation]` (default `[ ]`)
+    : A treefmt module. See [options reference].
+
+    [options reference]: https://nixos.org/manual/nixpkgs/unstable#sec-treefmt-options-reference
   */
   withConfig =
     module:

pkgs/by-name/tr/treefmt/options-doc.nix

@@ -0,0 +1,31 @@
+# To build this derivation, run `nix-build -A treefmt.optionsDoc`
+{
+  lib,
+  treefmt,
+  nixosOptionsDoc,
+}:
+
+let
+  configuration = treefmt.evalConfig [ ];
+
+  root = toString configuration._module.specialArgs.modulesPath;
+  revision = lib.trivial.revisionWithDefault "master";
+  removeRoot = file: lib.removePrefix "/" (lib.removePrefix root file);
+
+  transformDeclaration =
+    file:
+    let
+      fileStr = toString file;
+      subpath = "pkgs/by-name/tr/treefmt/modules/" + removeRoot fileStr;
+    in
+    assert lib.hasPrefix root fileStr;
+    {
+      url = "https://github.com/NixOS/nixpkgs/blob/${revision}/${subpath}";
+      name = subpath;
+    };
+in
+nixosOptionsDoc {
+  documentType = "none";
+  options = builtins.removeAttrs configuration.options [ "_module" ];
+  transformOptions = opt: opt // { declarations = map transformDeclaration opt.declarations; };
+}

pkgs/by-name/tr/treefmt/package.nix

@@ -39,6 +39,9 @@ buildGoModule rec {
 
     # Documentation for functions defined in `./lib.nix`
     functionsDoc = callPackages ./functions-doc.nix { };
+
+    # Documentation for options declared in `treefmt.evalConfig` configurations
+    optionsDoc = callPackages ./options-doc.nix { };
   };
 
   meta = {