flake/modules: return manpage package as a singleton

configuration.nix

@@ -7,9 +7,11 @@ inputs: let
     lib ? pkgs.lib,
     check ? true,
     extraSpecialArgs ? {},
+    extraModules ? [],
+    ...
   }:
     modulesWithInputs {
-      inherit pkgs lib check extraSpecialArgs;
+      inherit pkgs lib check extraSpecialArgs extraModules;
       configuration.imports = modules;
     };
 

flake/modules/home-manager.nix

@@ -6,8 +6,8 @@ packages: inputs: {
   ...
 }: let
   inherit (lib) maintainers;
-  inherit (lib.modules) mkIf mkMerge;
-  inherit (lib.lists) optionals;
+  inherit (lib.modules) mkIf;
+  inherit (lib.lists) optional;
   inherit (lib.options) mkOption mkEnableOption literalExpression;
   inherit (lib.types) attrsOf anything bool;
 
@@ -74,16 +74,14 @@ in {
     };
   };
 
-  config = mkIf cfg.enable mkMerge [
-    {
-      programs.neovim-flake.finalPackage = neovimConfigured.neovim;
+  config = mkIf cfg.enable {
+    programs.neovim-flake.finalPackage = neovimConfigured.neovim;
 
-      home = {
-        sessionVariables.EDITOR = mkIf cfg.defaultEditor (lib.mkOverride 900 "nvim");
-        packages =
-          [cfg.finalPackage]
-          ++ optionals cfg.enableManpages packages.${pkgs.stdenv.system}.docs-manpages;
-      };
-    }
-  ];
+    home = {
+      sessionVariables = mkIf cfg.defaultEditor {EDITOR = "nvim";};
+      packages =
+        [cfg.finalPackage]
+        ++ optional cfg.enableManpages packages.${pkgs.stdenv.system}.docs-manpages;
+    };
+  };
 }

flake/modules/nixos.nix

@@ -6,8 +6,8 @@ packages: inputs: {
   ...
 }: let
   inherit (lib) maintainers;
-  inherit (lib.modules) mkIf mkMerge;
-  inherit (lib.lists) optionals;
+  inherit (lib.modules) mkIf mkOverride;
+  inherit (lib.lists) optional;
   inherit (lib.options) mkOption mkEnableOption literalExpression;
   inherit (lib.types) attrsOf anything bool;
 
@@ -74,16 +74,14 @@ in {
     };
   };
 
-  config = mkIf cfg.enable mkMerge [
-    {
-      programs.neovim-flake.finalPackage = neovimConfigured.neovim;
+  config = mkIf cfg.enable {
+    programs.neovim-flake.finalPackage = neovimConfigured.neovim;
 
-      environment = {
-        variables.EDITOR = mkIf cfg.defaultEditor (lib.mkOverride 900 "nvim");
-        systemPackages =
-          [cfg.finalPackage]
-          ++ optionals cfg.enableManpages packages.${pkgs.stdenv.system}.docs-manpages;
-      };
-    }
-  ];
+    environment = {
+      variables.EDITOR = mkIf cfg.defaultEditor (mkOverride 900 "nvim");
+      systemPackages =
+        [cfg.finalPackage]
+        ++ optional cfg.enableManpages packages.${pkgs.stdenv.system}.docs-manpages;
+    };
+  };
 }

modules/default.nix

@@ -4,30 +4,43 @@ inputs: {
   lib ? pkgs.lib,
   check ? true,
   extraSpecialArgs ? {},
+  extraModules ? [],
 }: let
   inherit (builtins) map filter isString toString getAttr;
   inherit (pkgs) wrapNeovimUnstable vimPlugins;
   inherit (pkgs.vimUtils) buildVimPlugin;
   inherit (pkgs.neovimUtils) makeNeovimConfig;
+  inherit (lib.lists) concatLists;
   inherit (lib.attrsets) recursiveUpdate;
   inherit (lib.asserts) assertMsg;
 
+  # call the extedended library with `lib` and `inputs` as arguments
+  # lib is used to provide the standard library functions to the extended library
+  # but it can be overridden while this file is being called
+  # inputs is used to pass inputs to the plugin autodiscovery function
   extendedLib = import ../lib/stdlib-extended.nix lib inputs;
 
+  # import modules.nix with `check`, `pkgs` and `lib` as arguments
+  # check can be disabled while calling this file is called
+  # to avoid checking in all modules
   nvimModules = import ./modules.nix {
     inherit check pkgs;
     lib = extendedLib;
   };
 
+  # evaluate the extended library with the modules
+  # optionally with any additional modules passed by the user
   module = extendedLib.evalModules {
-    modules = [configuration] ++ nvimModules;
     specialArgs = recursiveUpdate {modulesPath = toString ./.;} extraSpecialArgs;
+    modules = concatLists [[configuration] nvimModules extraModules];
   };
 
+  # alias to the internal configuration
   vimOptions = module.config.vim;
 
-  extraLuaPackages = ps: map (x: ps.${x}) vimOptions.luaPackages;
-
+  # build a vim plugin with the given name and arguments
+  # if the plugin is nvim-treesitter, warn the user to use buildTreesitterPlug
+  # instead
   buildPlug = {pname, ...} @ args:
     assert assertMsg (pname != "nvim-treesitter") "Use buildTreesitterPlug for building nvim-treesitter.";
       buildVimPlugin (args
@@ -60,24 +73,36 @@ inputs: {
       (f: f != null)
       plugins);
 
-  plugins =
-    (buildConfigPlugins vimOptions.startPlugins)
-    ++ (map (package: {
-        plugin = package;
-        optional = false;
-      })
-      (buildConfigPlugins
-        vimOptions.optPlugins));
+  # built (or "normalized") plugins that are modified
+  builtStartPlugins = buildConfigPlugins vimOptions.startPlugins;
+  builtOptPlugins = map (package: {
+    plugin = package;
+    optional = false;
+  }) (buildConfigPlugins vimOptions.optPlugins);
 
-  neovim = wrapNeovimUnstable vimOptions.package (makeNeovimConfig {
-    inherit (vimOptions) viAlias;
-    inherit (vimOptions) vimAlias;
-    inherit extraLuaPackages;
-    inherit plugins;
+  plugins = builtStartPlugins ++ builtOptPlugins;
+
+  extraLuaPackages = ps: map (x: ps.${x}) vimOptions.luaPackages;
+
+  # wrap user's desired neovim package using the neovim wrapper from nixpkgs
+  # the wrapper takes the following arguments:
+  #  - withPython (bool)
+  #  - extraPython3Packages (lambda)
+  #  - withNodeJs (bool)
+  #  - withRuby (bool)
+  #  - extraLuaPackages (lambda)
+  #  - plugins (list)
+  #  - customRC (string)
+  # and returns the wrapped package
+  neovim-wrapped = wrapNeovimUnstable vimOptions.package (makeNeovimConfig {
+    inherit (vimOptions) viAlias vimAlias;
+    inherit plugins extraLuaPackages;
     customRC = vimOptions.builtConfigRC;
   });
 in {
   inherit (module) options config;
   inherit (module._module.args) pkgs;
-  inherit neovim;
+
+  # expose wrapped neovim-package
+  neovim = neovim-wrapped;
 }

modules/wrapper/build/config.nix

@@ -229,7 +229,9 @@ in {
           if [vim.enableLuaLoader](#opt-vim.enableLuaLoader) is set to true.
         '';
 
-        description = literalMD ''
+        example = literalExpression ''"$${builtins.readFile ./my-lua-config-pre.lua}"'';
+
+        description = ''
           Verbatim lua code that will be inserted **before**
           the result of `luaConfigRc` DAG has been resolved.
 
@@ -238,9 +240,11 @@ in {
           of lua configs after the DAG result.
 
           ::: {.warning}
-          You do not want to override this option. It is used
-          internally to set certain options as early as possible
-          and should be avoided unless you know what you're doing.
+          You do not want to override this option with mkForce
+          It is used internally to set certain options as early
+          as possible and should be avoided unless you know what
+          you're doing. Passing a string to this option will
+          merge it with the default contents.
           :::
         '';
       };
@@ -269,8 +273,9 @@ in {
       luaConfigPost = mkOption {
         type = str;
         default = "";
+        example = literalExpression ''"$${builtins.readFile ./my-lua-config-post.lua}"'';
         description = ''
-          Verbatim lua code that will be inserted after
+          Verbatim lua code that will be inserted **after**
           the result of the `luaConfigRc` DAG has been resolved
 
           This option **does not** take a DAG set, but a string