Merge 7b58caaa9f into ed31499ad6

docs/manual/configuring/custom-plugins/configuring.md

@@ -32,16 +32,18 @@ that the `extraPlugins` option has its own DAG scope), and the its setup code
 respectively. For example:
 
 ```nix
-config.vim.extraPlugins = with pkgs.vimPlugins; {
-  aerial = {
-    package = aerial-nvim;
-    setup = "require('aerial').setup {}";
-  };
+{pkgs, ...}: {
+  config.vim.extraPlugins = {
+    aerial = {
+      package = pkgs.vimPlugins.aerial-nvim;
+      setup = "require('aerial').setup {}";
+    };
 
-  harpoon = {
-    package = harpoon;
-    setup = "require('harpoon').setup {}";
-    after = ["aerial"]; # place harpoon configuration after aerial
+    harpoon = {
+      package = pkgs.vimPlugins.harpoon;
+      setup = "require('harpoon').setup {}";
+      after = ["aerial"]; # place harpoon configuration after aerial
+    };
   };
 }
 ```

docs/manual/configuring/custom-plugins/non-lazy-method.md

@@ -5,10 +5,10 @@ under `vim.extraPlugins`. Instead of using DAGs exposed by the library, you may
 use the extra plugin module as follows:
 
 ```nix
-{
-  config.vim.extraPlugins = with pkgs.vimPlugins; {
+{pkgs, ...}: {
+  config.vim.extraPlugins = {
     aerial = {
-      package = aerial-nvim;
+      package = pkgs.vimPlugins.aerial-nvim;
       setup = ''
         require('aerial').setup {
           -- some lua configuration here
@@ -17,7 +17,7 @@ use the extra plugin module as follows:
     };
 
     harpoon = {
-      package = harpoon;
+      package = pkgs.vimPlugins.harpoon;
       setup = "require('harpoon').setup {}";
       after = ["aerial"];
     };

docs/manual/tips.md

@@ -1,7 +1,8 @@
 # Helpful Tips {#ch-helpful-tips}
 
 ```{=include=} chapters
-tips/pure-lua-config.md
 tips/debugging-nvf.md
 tips/offline-docs.md
+tips/pure-lua-config.md
+tips/plugin-sources.md
 ```

docs/manual/tips/plugin-sources.md

@@ -0,0 +1,131 @@
+# Adding Plugins From Different Sources {#sec-plugin-sources}
+
+**nvf** attempts to avoid depending on Nixpkgs for Neovim plugins. For the most
+part, this is accomplished by defining each plugin's source and building them
+from source.
+
+[npins]: https://github.com/andir/npins
+
+To define plugin sources, we use [npins] and pin each plugin source using
+builtin fetchers. You are not bound by this restriction. In your own
+configuration, any kind of fetcher or plugin source is fine.
+
+## Nixpkgs & Friends {#ch-plugins-from-nixpkgs}
+
+`vim.startPlugins` and `vim.optPlugins` options take either a **string**, in
+which case a plugin from nvf's internal plugins registry will be used, or a
+**package**. If your plugin does not require any setup, or ordering for it s
+configuration, then it is possible to add it to `vim.startPlugins` to load it on
+startup.
+
+```nix
+{pkgs, ...}: {
+  # Aerial does require some setup. In the case you pass a plugin that *does*
+  # require manual setup, then you must also call the setup function.
+  vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
+}
+```
+
+[`vim.extraPlugins`]: https://notashelf.github.io/nvf/options.html#opt-vim.extraPlugins
+
+This will fetch aerial.nvim from nixpkgs, and add it to Neovim's runtime path to
+be loaded manually. Although for plugins that require manual setup, you are
+encouraged to use [`vim.extraPlugins`].
+
+```nix
+{
+  vim.extraPlugins = {
+    aerial = {
+      package = pkgs.vimPlugins.aerial-nvim;
+      setup = "require('aerial').setup {}";
+    };
+  };
+}
+```
+
+[custom plugins section]: https://notashelf.github.io/nvf/index.xhtml#ch-custom-plugins
+
+More details on the extraPlugins API is documented in the
+[custom plugins section].
+
+## Building Your Own Plugins {#ch-plugins-from-source}
+
+In the case a plugin is not available in Nixpkgs, or the Nixpkgs package is
+outdated (or, more likely, broken) it is possible to build the plugins from
+source using a tool, such as [npins]. You may also use your _flake inputs_ as
+sources.
+
+Example using plugin inputs:
+
+```nix
+{
+  # In your flake.nix
+  inputs = {
+    aerial-nvim = {
+      url = "github:stevearc/aerial.nvim"
+      flake = false;
+    };
+  };
+
+  # Make sure that 'inputs' is properly propagated into Nvf, for example, through
+  # specialArgs.
+  outputs = { ... };
+}
+```
+
+In the case, you may use the input directly for the plugin's source attribute in
+`buildVimPlugin`.
+
+```nix
+# Make sure that 'inputs' is properly propagated! It will be missing otherwise
+# and the resulting errors might be too obscure.
+{inputs, ...}: let
+  aerial-from-source = pkgs.vimUtils.buildVimPlugin {
+      name = "aerial-nvim";
+      src = inputs.aerial-nvim;
+    };
+in {
+  vim.extraPlugins = {
+    aerial = {
+      package = aerial-from-source;
+      setup = "require('aerial').setup {}";
+    };
+  };
+}
+```
+
+Alternatively, if you do not want to keep track of the source using flake inputs
+or npins, you may call `fetchFromGitHub` (or other fetchers) directly. An
+example would look like this.
+
+```nix
+regexplainer = buildVimPlugin {
+  name = "nvim-regexplainer";
+  src = fetchFromGitHub {
+    owner = "bennypowers";
+    repo = "nvim-regexplainer";
+    rev = "4250c8f3c1307876384e70eeedde5149249e154f";
+    hash = "sha256-15DLbKtOgUPq4DcF71jFYu31faDn52k3P1x47GL3+b0=";
+  };
+
+  # The 'buildVimPlugin' imposes some "require checks" on all plugins build from
+  # source. Failing tests, if they are not relevant, can be disabled using the
+  # 'nvimSkipModule' argument to the 'buildVimPlugin' function.
+  nvimSkipModule = [
+    "regexplainer"
+    "regexplainer.buffers.init"
+    "regexplainer.buffers.popup"
+    "regexplainer.buffers.register"
+    "regexplainer.buffers.shared"
+    "regexplainer.buffers.split"
+    "regexplainer.component.descriptions"
+    "regexplainer.component.init"
+    "regexplainer.renderers.narrative.init"
+    "regexplainer.renderers.narrative.narrative"
+    "regexplainer.renderers.init"
+    "regexplainer.utils.defer"
+    "regexplainer.utils.init"
+    "regexplainer.utils.treesitter"
+  ];
+}
+```

modules/neovim/init/autocmds.nix

@@ -126,6 +126,20 @@ in {
     autocmds = mkOption {
       type = listOf autocommandType;
       default = [];
+      example = literalExpression ''
+        [
+          {
+           enable = true;
+            desc = "Highlight yanks on copy";
+            pattern = ["*"];
+            callback = lib.generators.mkLuaInline '''
+              function()
+                vim.highlight.on_yank({ timeout = 500 })
+              end
+            ''';
+          }
+        ]
+      '';
       description = ''
         A list of Neovim autocommands to be registered.
 

modules/wrapper/environment/options.nix

@@ -54,9 +54,7 @@ in {
 
     optPlugins = pluginsOpt {
       default = [];
-      example = ''
-        [pkgs.vimPlugins.vim-ghost]
-      '';
+      example = "[pkgs.vimPlugins.vim-ghost]";
       description = ''
         List of plugins to optionally load on startup.
 
@@ -73,8 +71,8 @@ in {
       type = attrsOf extraPluginType;
       default = {};
       description = ''
-        A list of plugins and their configurations that will be
-        set up after builtin plugins.
+        Plugins and their configurations that will be set up after
+        builtin plugins.
 
         This option takes a special type that allows you to order
         your custom plugins using nvf's modified DAG library.
@@ -82,17 +80,31 @@ in {
 
       example = literalMD ''
         ```nix
-        with pkgs.vimPlugins; {
+        {
           aerial = {
-            package = aerial-nvim;
+            package = pkgs.vimPlugins.aerial-nvim;
             setup = "require('aerial').setup {}";
           };
 
           harpoon = {
-            package = harpoon;
+            package = pkgs.vimPlugins.harpoon;
             setup = "require('harpoon').setup {}";
             after = ["aerial"]; # place harpoon configuration after aerial
           };
+
+          # Example for packages built from source
+          deferred-clipboard = {
+            package = buildVimPlugin {
+              name = "deferred-clipboard";
+              src = (fetchFromGitHub {
+                owner = "EtiamNullam";
+                repo = "deferred-clipboard.nvim";
+                rev = "810a29d166eaa41afc220cc7cd85eeaa3c43b37f";
+                hash = "sha256-nanNQEtpjv0YKEkkrPmq/5FPxq+Yj/19cs0Gf7YgKjU=";
+              };
+            });
+            setup = "require('deferred-clipboard').setup {}";
+          };
         }
         ```
       '';
@@ -101,21 +113,20 @@ in {
     extraPackages = mkOption {
       type = listOf package;
       default = [];
-      example = ''[pkgs.fzf pkgs.ripgrep]'';
+      example = "[pkgs.fzf pkgs.ripgrep]";
       description = ''
         List of additional packages to make available to the Neovim
         wrapper.
       '';
     };
 
-    # this defaults to `true` in the wrapper
+    # This defaults to `true` in the wrapper
     # and since we pass this value to the wrapper
     # with an inherit, it should be `true` here as well
     withRuby =
-      mkEnableOption ''
-        Ruby support in the Neovim wrapper.
-      ''
+      mkEnableOption ""
       // {
+        description = "Whether to enable Ruby support in the Neovim wrapper";
         default = true;
       };