From 710771af3d1c8c3f86a9e5d562616973ed5f3f21 Mon Sep 17 00:00:00 2001
From: Robert Helgesson <robert@rycee.net>
Date: Thu, 6 Feb 2025 00:50:42 +0100
Subject: [PATCH] docs: add a poison module

The poison module is intended to catch cases where the documentation
depends on the user's configuration. We want to keep such dependencies
to a minimum as it increases the risk of documentation rebuilds and
confusion caused by documentation being different depending on the
source.
---
 docs/default.nix | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/default.nix b/docs/default.nix
index 6887bd2bf..f15668955 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -76,9 +76,35 @@ let
       ...
     }:
     let
+      # to discourage references from option descriptions and defaults.
+      poisonModule =
+        let
+          poisonAttr = n: {
+            name = n;
+            value = abort ''
+              error: the option documentation has a dependency on the configuration.
+
+              You may, for example, have added an option attribute like
+
+                default = ''${config.some.value};
+
+              Since the default value is included in the Home Manager manual, this
+              would make the manual depend on the user's configuration.
+
+              To avoid this problem in this particular case, consider changing to
+
+                default = ''${config.some.value};
+                defaultText = lib.literalExpression "\\''${config.some.value}";'';
+          };
+        in
+        { options, ... }:
+        {
+          config = lib.listToAttrs (map poisonAttr (lib.filter (n: n != "_module") (lib.attrNames options)));
+        };
+
       options =
         (lib.evalModules {
-          inherit modules;
+          modules = modules ++ [ poisonModule ];
           class = "homeManager";
         }).options;
     in