From 3222c99a916f4019ecf1bc6d3c59f08294857b2e Mon Sep 17 00:00:00 2001
From: Emily <vcs@emily.moe>
Date: Fri, 30 Jun 2023 06:22:38 +0100
Subject: [PATCH] treewide: convert parameterized docs to Markdown

Parameterized documentation generators like this can't be converted
automatically.
---
 modules/files.nix           |  2 +-
 modules/lib/file-type.nix   |  2 +-
 modules/misc/xdg.nix        |  3 +--
 modules/programs/neovim.nix |  2 +-
 modules/systemd.nix         | 23 ++++++++++-------------
 5 files changed, 14 insertions(+), 18 deletions(-)

diff --git a/modules/files.nix b/modules/files.nix
index af52b58ca..c869df1d8 100644
--- a/modules/files.nix
+++ b/modules/files.nix
@@ -28,7 +28,7 @@ in
     home.file = mkOption {
       description = "Attribute set of files to link into the user home.";
       default = {};
-      type = fileType "home.file" "<envar>HOME</envar>" homeDirectory;
+      type = fileType "home.file" "{env}`HOME`" homeDirectory;
     };
 
     home-files = mkOption {
diff --git a/modules/lib/file-type.nix b/modules/lib/file-type.nix
index a67f6bb08..ce84209d6 100644
--- a/modules/lib/file-type.nix
+++ b/modules/lib/file-type.nix
@@ -32,7 +32,7 @@ in
             in
               removePrefix (homeDirectory + "/") absPath;
           defaultText = literalExpression "name";
-          description = ''
+          description = lib.mdDoc ''
             Path to target file relative to ${basePathDesc}.
           '';
         };
diff --git a/modules/misc/xdg.nix b/modules/misc/xdg.nix
index 3d2a72a06..23cbe72a2 100644
--- a/modules/misc/xdg.nix
+++ b/modules/misc/xdg.nix
@@ -34,8 +34,7 @@ in {
     };
 
     configFile = mkOption {
-      type = fileType "xdg.configFile" "<varname>xdg.configHome</varname>"
-        cfg.configHome;
+      type = fileType "xdg.configFile" "{var}`xdg.configHome`" cfg.configHome;
       default = { };
       description = ''
         Attribute set of files to link into the user's XDG
diff --git a/modules/programs/neovim.nix b/modules/programs/neovim.nix
index b57cfe065..a05191407 100644
--- a/modules/programs/neovim.nix
+++ b/modules/programs/neovim.nix
@@ -44,7 +44,7 @@ let
         # passing actual "${xdg.configHome}/nvim" as basePath was a bit tricky
         # due to how fileType.target is implemented
         type = fileType "programs.neovim.plugins._.runtime"
-          "<varname>xdg.configHome/nvim</varname>" "nvim";
+          "{var}`xdg.configHome/nvim`" "nvim";
         example = literalExpression ''
           { "ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc"; }
         '';
diff --git a/modules/systemd.nix b/modules/systemd.nix
index 68929ed1e..4762c18d0 100644
--- a/modules/systemd.nix
+++ b/modules/systemd.nix
@@ -59,13 +59,10 @@ let
   unitDescription = type: ''
     Definition of systemd per-user ${type} units. Attributes are
     merged recursively.
-    </para><para>
+
     Note that the attributes follow the capitalization and naming used
     by systemd. More details can be found in
-    <citerefentry>
-      <refentrytitle>systemd.${type}</refentrytitle>
-      <manvolnum>5</manvolnum>
-    </citerefentry>.
+    {manpage}`systemd.${type}(5)`.
   '';
 
   unitExample = type:
@@ -109,56 +106,56 @@ in {
       services = mkOption {
         default = { };
         type = unitType "service";
-        description = unitDescription "service";
+        description = lib.mdDoc (unitDescription "service");
         example = unitExample "Service";
       };
 
       slices = mkOption {
         default = { };
         type = unitType "slice";
-        description = unitDescription "slice";
+        description = lib.mdDoc (unitDescription "slice");
         example = unitExample "Slice";
       };
 
       sockets = mkOption {
         default = { };
         type = unitType "socket";
-        description = unitDescription "socket";
+        description = lib.mdDoc (unitDescription "socket");
         example = unitExample "Socket";
       };
 
       targets = mkOption {
         default = { };
         type = unitType "target";
-        description = unitDescription "target";
+        description = lib.mdDoc (unitDescription "target");
         example = unitExample "Target";
       };
 
       timers = mkOption {
         default = { };
         type = unitType "timer";
-        description = unitDescription "timer";
+        description = lib.mdDoc (unitDescription "timer");
         example = unitExample "Timer";
       };
 
       paths = mkOption {
         default = { };
         type = unitType "path";
-        description = unitDescription "path";
+        description = lib.mdDoc (unitDescription "path");
         example = unitExample "Path";
       };
 
       mounts = mkOption {
         default = { };
         type = unitType "mount";
-        description = unitDescription "mount";
+        description = lib.mdDoc (unitDescription "mount");
         example = unitExample "Mount";
       };
 
       automounts = mkOption {
         default = { };
         type = unitType "automount";
-        description = unitDescription "automount";
+        description = lib.mdDoc (unitDescription "automount");
         example = unitExample "Automount";
       };