doc/neovim: better document the wrappers (#373805)

* doc/neovim: better document the wrappers

there is new wrapper interface `wrapNeovimUnstable` in development intended to be
easier to use than the old `wrapNeovim`. It provides new fancy features that we would like to
leverage/advertise
The interface is not definitive yet so we provide a translation layer
to avoid breaking user configurations such that `wrapNeovim` still works.
This explains why we document both at the moment with the goal to remove
the old one once we ciment the interface.

* doc/neovim: explain what buildNeovimPlugin does

doc/languages-frameworks/neovim.section.md

@@ -1,22 +1,40 @@
 # Neovim {#neovim}
 
 Install `neovim-unwrapped` to get a barebone neovim to configure imperatively.
-Neovim can be configured to include your favorite plugins and additional libraries by installing `neovim` instead.
+This is the closest to what you encounter on other distributions.
+
+`neovim` is a wrapper around neovim with some extra configuration to for
+instance set the various language providers like python.
+The wrapper can be further configured to include your favorite plugins and
+configurations for a reproducible neovim across machines.
 See the next section for more details.
 
 ## Custom configuration {#neovim-custom-configuration}
 
-For Neovim the `configure` argument can be overridden to achieve the same:
+There are two wrappers available to provide additionnal configuration around the vanilla package `pkgs.neovim-unwrapped`:
+1. `wrapNeovim`: the historical one you should use
+2. `wrapNeovimUnstable` intended to replace the former. It has more features but
+   the interface is not stable yet.
+
+You can configure the former via:
 
 ```nix
 neovim.override {
   configure = {
     customRC = ''
       # here your custom configuration goes!
     '';
+    packages.myVimPackage = with pkgs.vimPlugins; {
+      # See examples below on how to use custom packages.
+      start = [ ];
+      # If a Vim plugin has a dependency that is not explicitly listed in
+      # `opt`, that dependency will always be added to `start` to avoid confusion.
+      opt = [ ];
+    };
   };
 }
 ```
+`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
 
 If you want to use `neovim-qt` as a graphical editor, you can configure it by overriding Neovim in an overlay
 or passing it an overridden Neovim:
@@ -33,7 +51,77 @@ neovim-qt.override {
 }
 ```
 
+You can use the new unstable wrapper but the interface may change:
+- `autoconfigure`: certain plugins need a custom configuration to work with nix.
+For instance, `sqlite-lua` needs `g:sqlite_clib_path` to be set to work. Nixpkgs historically patched these in the plugins with several drawbacks: harder maintenance and making upstream work harder. Per convention, these mandatory bits of configuration are bookmarked in nixpkgs in `passthru.initLua`. Enabling `autoconfigure` automatically adds the snippets required for the plugins to work.
+- `autowrapRuntimeDeps`: Appends plugin's runtime dependencies to `PATH`. For instance, `rest.nvim` requires `curl` to work. Enabling `autowrapRuntimeDeps` adds it to the `PATH` visible by your Neovim wrapper (but not your global `PATH`).
+- `luaRcContent`: Extra lua code to add to the generated `init.lua`.
+- `neovimRcContent`: Extra vimL code sourced by the generated `init.lua`.
+- `wrapperArgs`: Extra arguments forwarded to the `makeWrapper` call.
+- `wrapRc`: Nix, not being able to write in your `$HOME`, loads the
+  generated Neovim configuration via its  `-u` argument, i.e. : `-u /nix/store/...generatedInit.lua`. This has side effects like preventing Neovim from reading your config in `$XDG_CONFIG_HOME` (see bullet 7 of [`:help startup`](https://neovim.io/doc/user/starting.html#_initialization) in Neovim). Disable it if you want to generate your own wrapper. You can still reuse while reusing the logic of the nixpkgs wrapper and access the generated config via `neovim.passthru.initRc`.
+- `plugins`: A list of plugins to add to the wrapper.
+
+```
+wrapNeovimUnstable {
+  autoconfigure = true;
+  autowrapRuntimeDeps = true;
+  luaRcContent = ''
+    vim.o.sessionoptions = 'buffers,curdir,help,tabpages,winsize,winpos,localoptions'
+    vim.g.mapleader = ' '
+    vim.g.maplocalleader = ' '
+    vim.opt.smoothscroll = true
+    vim.opt.colorcolumn = { 100 }
+    vim.opt.termguicolors = true
+  '';
+  # plugins accepts a list of either plugins or { plugin = ...; config = ..vimscript.. };
+  plugins = with vimPlugins; [
+    {
+      plugin = vim-obsession;
+      config = ''
+        map <Leader>$ <Cmd>Obsession<CR>
+      '';
+    }
+    (nvim-treesitter.withPlugins (p: [ p.nix p.python ]))
+    hex-nvim
+  ];
+}
+```
+
+You can explore the configuration with`nix repl` to discover these options and
+override them. For instance:
+```nix
+neovim.overrideAttrs(oldAttrs: {
+   autowrapRuntimeDeps = false;
+})
+```
+
 ### Specificities for some plugins {#neovim-plugin-specificities}
+
+### Plugin optional configuration {#neovim-plugin-required-snippet}
+
+Some plugins require specific configuration to work. We choose not to
+patch those plugins but expose the necessary configuration under
+`PLUGIN.passthru.initLua` for neovim plugins. For instance, the `unicode-vim` plugin
+needs the path towards a unicode database so we expose the following snippet `vim.g.Unicode_data_directory="${self.unicode-vim}/autoload/unicode"` under `vimPlugins.unicode-vim.passthru.initLua`.
+
+#### {#neovim-luarocks-based-plugins}
+
+In order to automatically handle plugin dependencies, several neovim plugins
+upload their package to [](www.luarocks.org). This means less work for nixpkgs maintainers in the long term as dependencies get updated automatically.
+This means several neovim plugins are first packaged as nixpkgs [lua
+packages](#packaging-a-library-on-luarocks), and converted via `buildNeovimPlugin` in
+a vim plugin. This conversion is necessary because neovim expects lua folders to be
+top-level while luarocks installs them in varous subfolders by default.
+
+For instance:
+```nix
+rtp-nvim = neovimUtils.buildNeovimPlugin {
+    luaAttr = luaPackages.rtp-nvim;
+};
+```
+To update these packages, you should use the lua updater rather than vim's.
+
 #### Treesitter {#neovim-plugin-treesitter}
 
 By default `nvim-treesitter` encourages you to download, compile and install

doc/languages-frameworks/vim.section.md

@@ -58,25 +58,6 @@ vim-full.customize {
 }
 ```
 
-`myVimPackage` is an arbitrary name for the generated package. You can choose any name you like.
-For Neovim the syntax is:
-
-```nix
-neovim.override {
-  configure = {
-    customRC = ''
-      # here your custom configuration goes!
-    '';
-    packages.myVimPackage = with pkgs.vimPlugins; {
-      # see examples below how to use custom packages
-      start = [ ];
-      # If a Vim plugin has a dependency that is not explicitly listed in
-      # opt that dependency will always be added to start to avoid confusion.
-      opt = [ ];
-    };
-  };
-}
-```
 
 The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
 
@@ -178,15 +159,6 @@ To add a new plugin, run `nix-shell -p vimPluginsUpdater --run 'vim-plugins-upda
 
 Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `vimPluginsUpdater` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of the Language Server Protocol integration with Vim/Neovim.
 
-
-### Plugin optional configuration {#vim-plugin-required-snippet}
-
-Some plugins require specific configuration to work. We choose not to
-patch those plugins but expose the necessary configuration under
-`PLUGIN.passthru.initLua` for neovim plugins. For instance, the `unicode-vim` plugin
-needs the path towards a unicode database so we expose the following snippet `vim.g.Unicode_data_directory="${self.unicode-vim}/autoload/unicode"` under `vimPlugins.unicode-vim.passthru.initLua`.
-
-
 ## Updating plugins in nixpkgs {#updating-plugins-in-nixpkgs}
 
 Run the update script with a GitHub API token that has at least `public_repo` access. Running the script without the token is likely to result in rate-limiting (429 errors). For steps on creating an API token, please refer to [GitHub's token documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token).

doc/redirects.json

@@ -8,6 +8,9 @@
   "neovim-custom-configuration": [
     "index.html#neovim-custom-configuration"
   ],
+  "neovim-luarocks-based-plugins": [
+    "index.html#neovim-luarocks-based-plugins"
+  ],
   "nixpkgs-manual": [
     "index.html#nixpkgs-manual"
   ],
@@ -3799,7 +3802,8 @@
   "testing-neovim-plugins-neovim-require-check": [
     "index.html#testing-neovim-plugins-neovim-require-check"
   ],
-  "vim-plugin-required-snippet": [
+  "neovim-plugin-required-snippet": [
+    "index.html#neovim-plugin-required-snippet",
     "index.html#vim-plugin-required-snippet"
   ],
   "updating-plugins-in-nixpkgs": [