From fb1bc8de93d3c2dba328224a082ecf1ad2fc7fac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Na=C3=AFm=20Favier?= <n@monade.li>
Date: Sun, 8 Jan 2023 22:41:13 +0100
Subject: [PATCH] lib/modules: make `mkAliasOptionModule` emit DocBook

Follow-up to https://github.com/NixOS/nixpkgs/pull/208407

Removing `mdDoc` isn't enough, we need to emit actual DocBook.
---
 lib/modules.nix                        | 8 +++++---
 nixos/lib/make-options-doc/default.nix | 1 +
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/lib/modules.nix b/lib/modules.nix
index c304d5b9afd..5e6bee6aabe 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1113,7 +1113,6 @@ rec {
     visible = true;
     warn = false;
     use = id;
-    wrapDescription = lib.id;
   };
 
   /* Transitional version of mkAliasOptionModule that uses MD docs. */
@@ -1122,6 +1121,7 @@ rec {
     visible = true;
     warn = false;
     use = id;
+    markdown = true;
   };
 
   /* mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b
@@ -1144,7 +1144,7 @@ rec {
       (opt.highestPrio or defaultOverridePriority)
       (f opt.value);
 
-  doRename = { from, to, visible, warn, use, withPriority ? true, wrapDescription ? lib.mdDoc }:
+  doRename = { from, to, visible, warn, use, withPriority ? true, markdown ? false }:
     { config, options, ... }:
     let
       fromOpt = getAttrFromPath from options;
@@ -1155,7 +1155,9 @@ rec {
     {
       options = setAttrByPath from (mkOption {
         inherit visible;
-        description = wrapDescription "Alias of {option}`${showOption to}`.";
+        description = if markdown
+          then lib.mdDoc "Alias of {option}`${showOption to}`."
+          else "Alias of <option>${showOption to}</option>.";
         apply = x: use (toOf config);
       } // optionalAttrs (toType != null) {
         type = toType;
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index a3436caad8f..ecd8350b959 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -41,6 +41,7 @@
 # characteristics but (hopefully) indistinguishable output.
 , allowDocBook ? true
 # whether lib.mdDoc is required for descriptions to be read as markdown.
+# !!! when this is eventually flipped to true, `lib.doRename` should also default to emitting Markdown
 , markdownByDefault ? false
 }: