Merge pull request #64753 from malob/update-add-vim-plugin-docs

Updating documentation about adding new Vim plugins

1 files changed, 95 insertions, 73 deletions

diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index c450a09f7bd..537e7b93e52 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/doc/languages-frameworks/vim.section.md
@@ -21,7 +21,7 @@ At the moment we support three different methods for managing plugins:
 
 Adding custom .vimrc lines can be done using the following code:
 
-```
+```nix
 vim_configurable.customize {
   # `name` specifies the name of the executable and package
   name = "vim-with-plugins";
@@ -32,11 +32,11 @@ vim_configurable.customize {
 }
 ```
 
-This configuration is used when vim is invoked with the command specified as name, in this case `vim-with-plugins`.
+This configuration is used when Vim is invoked with the command specified as name, in this case `vim-with-plugins`.
 
 For Neovim the `configure` argument can be overridden to achieve the same:
 
-```
+```nix
 neovim.override {
   configure = {
     customRC = ''
@@ -46,10 +46,10 @@ neovim.override {
 }
 ```
 
-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 neovimn:
+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 Neovimn:
 
-```
+```nix
 neovim-qt.override {
   neovim = neovim.override {
     configure = {
@@ -63,16 +63,16 @@ neovim-qt.override {
 
 ## Managing plugins with Vim packages
 
-To store you plugins in Vim packages (the native vim plugin manager, see `:help packages`) the following example can be used:
+To store you plugins in Vim packages (the native Vim plugin manager, see `:help packages`) the following example can be used:
 
-```
+```nix
 vim_configurable.customize {
   vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
     # loaded on launch
     start = [ youcompleteme fugitive ];
     # manually loadable by calling `:packadd $plugin-name`
-    # however, 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.
+    # however, 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 = [ phpCompletion elm-vim ];
     # To automatically load a plugin when opening a filetype, add vimrc lines like:
     # autocmd FileType php :packadd phpCompletion
@@ -83,7 +83,7 @@ vim_configurable.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 = ''
@@ -92,7 +92,7 @@ neovim.override {
     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
+      # 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 = [ ];
     };
@@ -102,7 +102,7 @@ neovim.override {
 
 The resulting package can be added to `packageOverrides` in `~/.nixpkgs/config.nix` to make it installable:
 
-```
+```nix
 {
   packageOverrides = pkgs: with pkgs; {
     myVim = vim_configurable.customize {
@@ -126,7 +126,7 @@ After that you can install your special grafted `myVim` or `myNeovim` packages.
 To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim
 plugins the following example can be used:
 
-```
+```nix
 vim_configurable.customize {
   vimrcConfig.packages.myVimPackage = with pkgs.vimPlugins; {
     # loaded on launch
@@ -137,7 +137,7 @@ vim_configurable.customize {
 
 For Neovim the syntax is:
 
-```
+```nix
 neovim.override {
   configure = {
     customRC = ''
@@ -161,89 +161,112 @@ assuming that "using latest version" is ok most of the time.
 
 First create a vim-scripts file having one plugin name per line. Example:
 
-    "tlib"
-    {'name': 'vim-addon-sql'}
-    {'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']}
+```
+"tlib"
+{'name': 'vim-addon-sql'}
+{'filetype_regex': '\%(vim)$', 'names': ['reload', 'vim-dev-plugin']}
+```
 
 Such vim-scripts file can be read by VAM as well like this:
 
-    call vam#Scripts(expand('~/.vim-scripts'), {})
+```vim
+call vam#Scripts(expand('~/.vim-scripts'), {})
+```
 
 Create a default.nix file:
 
-    { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
-    nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
+```nix
+{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
+nixpkgs.vim_configurable.customize { name = "vim"; vimrcConfig.vam.pluginDictionaries = [ "vim-addon-vim2nix" ]; }
+```
 
 Create a generate.vim file:
 
-    ActivateAddons vim-addon-vim2nix
-    let vim_scripts = "vim-scripts"
-    call nix#ExportPluginsForNix({
-    \  'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"],
-    \  'cache_file': '/tmp/vim2nix-cache',
-    \  'try_catch': 0,
-    \  'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
-    \ })
+```vim
+ActivateAddons vim-addon-vim2nix
+let vim_scripts = "vim-scripts"
+call nix#ExportPluginsForNix({
+\  'path_to_nixpkgs': eval('{"'.substitute(substitute(substitute($NIX_PATH, ':', ',', 'g'), '=',':', 'g'), '\([:,]\)', '"\1"',"g").'"}')["nixpkgs"],
+\  'cache_file': '/tmp/vim2nix-cache',
+\  'try_catch': 0,
+\  'plugin_dictionaries': ["vim-addon-manager"]+map(readfile(vim_scripts), 'eval(v:val)')
+\ })
+```
 
 Then run
 
-    nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'"
+```bash
+nix-shell -p vimUtils.vim_with_vim2nix --command "vim -c 'source generate.vim'"
+```
 
 You should get a Vim buffer with the nix derivations (output1) and vam.pluginDictionaries (output2).
-You can add your vim to your system's configuration file like this and start it by "vim-my":
+You can add your Vim to your system's configuration file like this and start it by "vim-my":
 
-    my-vim =
-     let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
-          copy paste output1 here
-     }; in vim_configurable.customize {
-       name = "vim-my";
-
-       vimrcConfig.vam.knownPlugins = plugins; # optional
-       vimrcConfig.vam.pluginDictionaries = [
-          copy paste output2 here
-       ];
-
-       # Pathogen would be
-       # vimrcConfig.pathogen.knownPlugins = plugins; # plugins
-       # vimrcConfig.pathogen.pluginNames = ["tlib"];
-     };
+```
+my-vim =
+  let plugins = let inherit (vimUtils) buildVimPluginFrom2Nix; in {
+    copy paste output1 here
+  }; in vim_configurable.customize {
+    name = "vim-my";
+
+    vimrcConfig.vam.knownPlugins = plugins; # optional
+    vimrcConfig.vam.pluginDictionaries = [
+       copy paste output2 here
+    ];
 
+    # Pathogen would be
+    # vimrcConfig.pathogen.knownPlugins = plugins; # plugins
+    # vimrcConfig.pathogen.pluginNames = ["tlib"];
+  };
+```
 
 Sample output1:
 
-    "reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
-      name = "reload";
-      src = fetchgit {
-        url = "git://github.com/xolox/vim-reload";
-        rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1";
-        sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh";
-      };
-      dependencies = ["nim-misc"];
+```
+"reload" = buildVimPluginFrom2Nix { # created by nix#NixDerivation
+  name = "reload";
+  src = fetchgit {
+    url = "git://github.com/xolox/vim-reload";
+    rev = "0a601a668727f5b675cb1ddc19f6861f3f7ab9e1";
+    sha256 = "0vb832l9yxj919f5hfg6qj6bn9ni57gnjd3bj7zpq7d4iv2s4wdh";
+  };
+  dependencies = ["nim-misc"];
 
-    };
-    [...]
+};
+[...]
+```
 
 Sample output2:
 
-    [
-      ''vim-addon-manager''
-      ''tlib''
-      { "name" = ''vim-addon-sql''; }
-      { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
-    ]
-
+```nix
+[
+  ''vim-addon-manager''
+  ''tlib''
+  { "name" = ''vim-addon-sql''; }
+  { "filetype_regex" = ''\%(vim)$$''; "names" = [ ''reload'' ''vim-dev-plugin'' ]; }
+]
+```
 
 ## Adding new plugins to nixpkgs
 
-In `pkgs/misc/vim-plugins/vim-plugin-names` we store the plugin names
-for all vim plugins we automatically generate plugins for.
-The format of this file `github username/github repository`:
-For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
-After adding your plugin to this file run the `./update.py` in the same folder.
-This will updated a file called `generated.nix` and make your plugin accessible in the
-`vimPlugins` attribute set (`vimPlugins.nerdtree` in our example).
-If additional steps to the build process of the plugin are required, add an
-override to the `pkgs/misc/vim-plugins/default.nix` in the same directory.
+Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
+
+Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
+
+```
+deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
+  dependencies = with super; [ deoplete-nvim vim-fish ];
+});
+```
+
+Sometimes plugins require an override that must be changed when the plugin is updated. This can cause issues when Vim plugins are auto-updated but the associated override isn't updated. For these plugins, the override should be written so that it specifies all information required to install the plugin, and running `./update.py` doesn't change the derivation for the plugin. Manually updating the override is required to update these types of plugins. An example of such a plugin is `LanguageClient-neovim`.
+
+To add a new plugin:
+
+  1. run `./update.py` and create a commit named "vimPlugins: Update",
+  2. add the new plugin to [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names) and add overrides if required to [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix),
+  3. run `./update.py` again and create a commit named "vimPlugins.[name]: init at [version]" (where `name` and `version` can be found in [generated.nix](/pkgs/misc/vim-plugins/generated.nix)), and
+  4. create a pull request.
 
 ## Important repositories
 
@@ -252,4 +275,3 @@ override to the `pkgs/misc/vim-plugins/default.nix` in the same directory.
 
 - [vim2nix](https://github.com/MarcWeber/vim-addon-vim2nix) which generates the
   .nix code
-