From 82a24d0d422bcc24eb33ebe7aa2571a78f4eafdf Mon Sep 17 00:00:00 2001
From: traxys <quentin+dev@familleboyer.net>
Date: Tue, 20 Feb 2024 21:20:59 +0100
Subject: [PATCH] docs: Allow to add an url in the online documentation (#1139)

* plugin/committia: Use correct maintainers import

* plugins/neocord: Remove redyf as the entry is not in the list

* docs: Allow to add an URL to the plugin
---
 docs/mdbook/default.nix   | 27 +++++++++++++++++++++++++-
 flake-modules/modules.nix | 41 +++++++++++++++++++++++++++++++++++++++
 lib/neovim-plugin.nix     |  9 ++++++++-
 lib/vim-plugin.nix        | 12 +++++++++++-
 plugins/git/committia.nix |  3 +--
 plugins/utils/neocord.nix |  2 +-
 6 files changed, 88 insertions(+), 6 deletions(-)

diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix
index 7ecc712b..b576c75d 100644
--- a/docs/mdbook/default.nix
+++ b/docs/mdbook/default.nix
@@ -12,6 +12,8 @@ with lib; let
     specialArgs = {inherit pkgs lib helpers;};
   };
 
+  inherit (options.config.meta) nixvimInfo;
+
   mkMDDoc = options:
     (nixosOptionsDoc {
       inherit options transformOptions;
@@ -59,6 +61,17 @@ with lib; let
         then opts
         else filterAttrs (_: component: component.isOption && (isVisible component)) opts;
       path = removeWhitespace (concatStringsSep "/" path);
+      moduleDoc =
+        if builtins.length path >= 2 && lib.hasAttrByPath path nixvimInfo
+        then let
+          info = lib.getAttrFromPath path nixvimInfo;
+          maintainers = options.config.meta.maintainers."${info.file}" or null;
+        in
+          "# ${lib.last path}\n\n"
+          + (lib.optionalString (maintainers != null && builtins.length maintainers > 0)
+            "Maintainers: ${lib.concatStringsSep ", " (builtins.map (m: m.name) maintainers)}\n\n")
+          + (lib.optionalString (info.url != null) "Url: [${info.url}](${info.url})\n\n")
+        else null;
     };
 
     components =
@@ -114,6 +127,7 @@ with lib; let
             index = {
               options = {};
               path = removeWhitespace "${group}";
+              moduleDoc = null;
             };
             components = {};
             isGroup = true;
@@ -183,7 +197,18 @@ with lib; let
         in
           (optionalString isBranch
             "mkdir -p ${opts.index.path}\n")
-          + "cp ${mkMDDoc opts.index.options} ${path}"
+          + (
+            if opts.index.moduleDoc == null
+            then "cp ${mkMDDoc opts.index.options} ${path}"
+            else ''
+              {
+              cat <<EOF
+              ${opts.index.moduleDoc}
+              EOF
+              cat ${mkMDDoc opts.index.options}
+              } > ${path}
+            ''
+          )
       )
       modules;
   };
diff --git a/flake-modules/modules.nix b/flake-modules/modules.nix
index 915aec02..48cf2eb4 100644
--- a/flake-modules/modules.nix
+++ b/flake-modules/modules.nix
@@ -17,6 +17,47 @@
       ../modules
       nixpkgsMaintainersList
       nixvimExtraArgsModule
+      ({lib, ...}:
+        with lib; {
+          # Attribute may contain the following fields:
+          #  - name: Name of the module
+          #  - kind: Either colorschemes or plugins
+          #  - url: Url for the plugin
+          #
+          #  [kind name] will identify the plugin
+          #
+          # We need to use an attrs instead of a submodule to handle the merge.
+          options.meta.nixvimInfo = mkOption {
+            type =
+              (types.nullOr types.attrs)
+              // {
+                # This will create an attrset of the form:
+                # {
+                #    "path"."to"."plugin" = { "<name>" = <info>; };
+                # }
+                #
+                # Where <info> is an attrset of the form:
+                # {file = "path"; url = null or "<URL>";}
+                merge = _: defs:
+                  lib.foldl' (acc: def:
+                    lib.recursiveUpdate acc {
+                      "${def.value.kind}"."${def.value.name}" = {
+                        inherit (def.value) url;
+                        inherit (def) file;
+                      };
+                    }) {
+                    plugins = {};
+                    colorschemes = {};
+                  }
+                  defs;
+              };
+            internal = true;
+            default = null;
+            description = ''
+              Nixvim related information on the module
+            '';
+          };
+        })
     ];
   };
 
diff --git a/lib/neovim-plugin.nix b/lib/neovim-plugin.nix
index 61ec28c7..c494a5e3 100644
--- a/lib/neovim-plugin.nix
+++ b/lib/neovim-plugin.nix
@@ -34,6 +34,7 @@ with lib; rec {
     name,
     namespace ? "plugins",
     maintainers,
+    url ? defaultPackage.meta.homepage,
     imports ? [],
     # deprecations
     deprecateExtraOptions ? false,
@@ -51,7 +52,13 @@ with lib; rec {
     extraPackages ? [],
     callSetup ? true,
   }: {
-    meta.maintainers = maintainers;
+    meta = {
+      inherit maintainers;
+      nixvimInfo = {
+        inherit name url;
+        kind = namespace;
+      };
+    };
 
     imports = let
       basePluginPath = [namespace name];
diff --git a/lib/vim-plugin.nix b/lib/vim-plugin.nix
index 63b1422e..7bfff16f 100644
--- a/lib/vim-plugin.nix
+++ b/lib/vim-plugin.nix
@@ -7,6 +7,10 @@ with lib; {
   mkVimPlugin = config: {
     name,
     namespace ? "plugins",
+    url ?
+      if defaultPackage != null
+      then defaultPackage.meta.homepage
+      else null,
     maintainers ? [],
     imports ? [],
     # deprecations
@@ -80,7 +84,13 @@ with lib; {
         };
       };
   in {
-    meta.maintainers = maintainers;
+    meta = {
+      inherit maintainers;
+      nixvimInfo = {
+        inherit name url;
+        kind = namespace;
+      };
+    };
     options.${namespace}.${name} =
       {
         enable = mkEnableOption originalName;
diff --git a/plugins/git/committia.nix b/plugins/git/committia.nix
index 14790f3b..8bdb2b45 100644
--- a/plugins/git/committia.nix
+++ b/plugins/git/committia.nix
@@ -1,5 +1,4 @@
 {
-  lib,
   config,
   helpers,
   pkgs,
@@ -12,7 +11,7 @@ helpers.vim-plugin.mkVimPlugin config {
   globalPrefix = "committia_";
   extraPackages = [pkgs.git];
 
-  maintainers = [lib.maintainers.alisonjenkins];
+  maintainers = [helpers.maintainers.alisonjenkins];
 
   settingsOptions = {
     open_only_vim_starting = helpers.defaultNullOpts.mkBool true ''
diff --git a/plugins/utils/neocord.nix b/plugins/utils/neocord.nix
index b0ff2ade..109e2ba4 100644
--- a/plugins/utils/neocord.nix
+++ b/plugins/utils/neocord.nix
@@ -10,7 +10,7 @@ with lib;
     name = "neocord";
     defaultPackage = pkgs.vimPlugins.neocord;
 
-    maintainers = [maintainers.redyf];
+    maintainers = [];
 
     settingsOptions = {
       # General options.