wrappers: Extend and document the makeNixvim function (nix-communit…

…y#86)

* wrappers: Allow to customize the nixpkgs used for nixvim

This allows to pass overlays and other such modifications of nixpkgs.

* wrappers: Allow to pass a custom module to nixvim

This is useful to be able to take full advantage of the Nix module
system, with `imports` and `options`.

* README: Update the documentation on the standalone usage

The following information were out of date or incomplete:

- The `build` function has be changed to the `makeNixvim` function.
- `makeNixvimWithModule` has been introduced in order to allow more
customization.
- Added a full example using nixvim in a standalone flake

README.md

@@ -80,23 +80,73 @@ you're not using it.
 
 ## Usage
 NixVim can be used in three ways: through the home-manager and NixOS modules,
-and through the `build` function. To use the modules, just import the
+and through the `makeNixvim` function. To use the modules, just import the
 `nixvim.homeManagerModules.${system}.nixvim` and
 `nixvim.nixosModules.${system}.nixvim` modules, depending on which system
 you're using.
 
-If you want to use it standalone, you can use the `build` function:
+If you want to use it standalone, you can use the `makeNixvim` function:
 
 ```nix
 { pkgs, nixvim, ... }: {
   environment.systemModules = [
-    (nixvim.build pkgs {
+    (nixvim.legacyPackages."${system}".makeNixvim {
       colorschemes.gruvbox.enable = true;
     })
   ];
 }
 ```
 
+Alternatively if you want a minimal flake to allow building a custom neovim you
+can use the following:
+
+```nix
+{
+  description = "A very basic flake";
+
+  inputs.nixvim.url = "github:pta2002/nixvim";
+  inputs.flake-utils.url = "github:numtide/flake-utils";
+
+  outputs = {
+    self,
+    nixpkgs,
+    nixvim,
+    flake-utils,
+  }: let
+    config = {
+      colorschemes.gruvbox.enable = true;
+    };
+  in
+    flake-utils.lib.eachDefaultSystem (system: let
+	  nixvim' = nixvim.legacyPackages."${system}";
+      nvim = nixvim'.makeNixvim config;
+    in {
+      packages = {
+        inherit nvim;
+        default = nvim;
+      };
+    });
+}
+```
+
+You can then run neovim using `nix run .# -- <file>`. This can be useful to test 
+config changes easily.
+
+### Advanced Usage
+
+You may want more control over the nixvim modules like:
+
+- Splitting your configuration in multiple files
+- Adding custom nix modules to enhance nixvim
+- Change the nixpkgs used by nixvim
+
+In this case you can use the `makeNixvimWithModule` function.
+
+It takes a set with the following keys:
+- `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the nixvim flake)
+- `module`: The nix module definition used to extend nixvim.
+  This is useful to pass additional module machinery like `options` or `imports`.
+
 ## How does it work?
 When you build the module (probably using home-manager), it will install all
 your plugins and generate a lua config for NeoVim with all the options

flake.nix

@@ -40,8 +40,14 @@
               packages.docs = pkgs.callPackage (import ./docs.nix) {
                 modules = nixvimModules;
               };
-
-              legacyPackages.makeNixvim = import ./wrappers/standalone.nix pkgs (modules pkgs);
+              legacyPackages = rec {
+                makeNixvimWithModule = import ./wrappers/standalone.nix pkgs modules;
+                makeNixvim = configuration: makeNixvimWithModule { 
+                  module = {
+                    config = configuration;
+                  };
+                };
+              };
             });
     in
     flakeOutput // {

wrappers/standalone.nix

@@ -1,4 +1,4 @@
-pkgs: modules: configuration:
+default_pkgs: modules: {pkgs ? default_pkgs, module}:
 
 let
 
@@ -7,7 +7,7 @@ let
   wrap = { wrapRc = true; };
 
   eval = lib.evalModules {
-    modules = modules ++ [ { config = configuration; } wrap ];
+    modules = (modules pkgs) ++ [ module wrap ];
   };
 
 in eval.config.finalPackage