From ec51c28cbd6eb7d8c2a7a6a112d6d296bc8e6c14 Mon Sep 17 00:00:00 2001 From: "Matthieu C." <886074+teto@users.noreply.github.com> Date: Sat, 11 Jan 2025 23:15:24 +0100 Subject: [PATCH] doc/neovim: move neovim to its own section I wanted to add instructions on how to configure neovim via the new wrapper but it was difficult mixing this with both the vim and old wrapper. Neovim differs enough from vim to warrant its own section IMO: 1. its wrapper is different (old wrapper close to vim's syntax, new one not so much) 2. treesitter is unique to neovim 3. the section about neovim plugins is unique to neovim as well. Not only that but it needs to expanded. At some point the doc unique to vim is going to exceed vim's. We can refer to vim's section to avoid duplication where it makes sense. --- doc/languages-frameworks/index.md | 1 + doc/languages-frameworks/neovim.section.md | 107 +++++++++++++++++++++ doc/languages-frameworks/vim.section.md | 102 +------------------- doc/redirects.json | 17 +++- 4 files changed, 123 insertions(+), 104 deletions(-) create mode 100644 doc/languages-frameworks/neovim.section.md diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index fe5f0e65a52e3..c3f192a1a38bf 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -96,4 +96,5 @@ swift.section.md tcl.section.md texlive.section.md vim.section.md +neovim.section.md ``` diff --git a/doc/languages-frameworks/neovim.section.md b/doc/languages-frameworks/neovim.section.md new file mode 100644 index 0000000000000..f26e4a2ffa4fc --- /dev/null +++ b/doc/languages-frameworks/neovim.section.md @@ -0,0 +1,107 @@ +# 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. +See the next section for more details. + +## Custom configuration {#neovim-custom-configuration} + +For Neovim the `configure` argument can be overridden to achieve the same: + +```nix +neovim.override { + configure = { + customRC = '' + # here your custom configuration goes! + ''; + }; +} +``` + +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: + +```nix +neovim-qt.override { + neovim = neovim.override { + configure = { + customRC = '' + # your custom configuration + ''; + }; + }; +} +``` + +### Specificities for some plugins {#neovim-plugin-specificities} +#### Treesitter {#neovim-plugin-treesitter} + +By default `nvim-treesitter` encourages you to download, compile and install +the required Treesitter grammars at run time with `:TSInstall`. This works +poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set +of precompiled grammars, you can use the `nvim-treesitter.withPlugins` function: + +```nix +(pkgs.neovim.override { + configure = { + packages.myPlugins = with pkgs.vimPlugins; { + start = [ + (nvim-treesitter.withPlugins ( + plugins: with plugins; [ + nix + python + ] + )) + ]; + }; + }; +}) +``` + +To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`. + + +### Testing Neovim plugins {#testing-neovim-plugins} + +#### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check} +`neovimRequireCheck` is a simple test which checks if Neovim can requires lua modules without errors. This is often enough to catch missing dependencies. + +It accepts a single string for a module, or a list of module strings to test. +- `nvimRequireCheck = MODULE;` +- `nvimRequireCheck = [ MODULE1 MODULE2 ];` + +When `nvimRequireCheck` is not specified, we will search the plugin's directory for lua modules to attempt loading. This quick smoke test can catch obvious dependency errors that might be missed. +The check hook will fail the build if any modules cannot be loaded. This encourages inspecting the logs to identify potential issues. + +To only check a specific module, add it manually to the plugin definition [overrides](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). + +```nix + gitsigns-nvim = super.gitsigns-nvim.overrideAttrs { + dependencies = [ self.plenary-nvim ]; + nvimRequireCheck = "gitsigns"; + }; +``` +Some plugins will have lua modules that require a user configuration to function properly or can contain optional lua modules that we dont want to test requiring. +We can skip specific modules using `nvimSkipModule`. Similar to `nvimRequireCheck`, it accepts a single string or a list of strings. +- `nvimSkipModule = MODULE;` +- `nvimSkipModule = [ MODULE1 MODULE2 ];` + +```nix + asyncrun-vim = super.asyncrun-vim.overrideAttrs { + nvimSkipModule = [ + # vim plugin with optional toggleterm integration + "asyncrun.toggleterm" + "asyncrun.toggleterm2" + ]; + }; +``` + +In rare cases, we might not want to actually test loading lua modules for a plugin. In those cases, we can disable `neovimRequireCheck` with `doCheck = false;`. + +This can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). +```nix + vim-test = super.vim-test.overrideAttrs { + # Vim plugin with a test lua file + doCheck = false; + }; +``` diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md index 0b5c26ef44a08..9d7dab9eb496a 100644 --- a/doc/languages-frameworks/vim.section.md +++ b/doc/languages-frameworks/vim.section.md @@ -1,7 +1,6 @@ # Vim {#vim} -Both Neovim and Vim can be configured to include your favorite plugins -and additional libraries. +Vim can be configured to include your favorite plugins and additional libraries. Loading can be deferred; see examples. @@ -19,7 +18,7 @@ build-time features are configurable. It has nothing to do with user configurati and both the `vim` and `vim-full` packages can be customized as explained in the next section. ::: -## Custom configuration {#custom-configuration} +## Custom configuration {#vim-custom-configuration} Adding custom .vimrc lines can be done using the following code: @@ -39,32 +38,6 @@ You can also omit `name` to customize Vim itself. See the [definition of `vimUtils.makeCustomizable`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-utils.nix#L408) for all supported options. -For Neovim the `configure` argument can be overridden to achieve the same: - -```nix -neovim.override { - configure = { - customRC = '' - # here your custom configuration goes! - ''; - }; -} -``` - -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: - -```nix -neovim-qt.override { - neovim = neovim.override { - configure = { - customRC = '' - # your custom configuration - ''; - }; - }; -} -``` ## Managing plugins with Vim packages {#managing-plugins-with-vim-packages} @@ -166,33 +139,6 @@ in If your package requires building specific parts, use instead `pkgs.vimUtils.buildVimPlugin`. -### Specificities for some plugins {#vim-plugin-specificities} -#### Treesitter {#vim-plugin-treesitter} - -By default `nvim-treesitter` encourages you to download, compile and install -the required Treesitter grammars at run time with `:TSInstall`. This works -poorly on NixOS. Instead, to install the `nvim-treesitter` plugins with a set -of precompiled grammars, you can use `nvim-treesitter.withPlugins` function: - -```nix -(pkgs.neovim.override { - configure = { - packages.myPlugins = with pkgs.vimPlugins; { - start = [ - (nvim-treesitter.withPlugins ( - plugins: with plugins; [ - nix - python - ] - )) - ]; - }; - }; -}) -``` - -To enable all grammars packaged in nixpkgs, use `pkgs.vimPlugins.nvim-treesitter.withAllGrammars`. - ## Managing plugins with vim-plug {#managing-plugins-with-vim-plug} To use [vim-plug](https://github.com/junegunn/vim-plug) to manage your Vim @@ -232,50 +178,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. -### Testing Neovim plugins {#testing-neovim-plugins} - -#### neovimRequireCheck {#testing-neovim-plugins-neovim-require-check} -`neovimRequireCheck` is a simple test which checks if Neovim can requires lua modules without errors. This is often enough to catch missing dependencies. - -It accepts a single string for a module, or a list of module strings to test. -- `nvimRequireCheck = MODULE;` -- `nvimRequireCheck = [ MODULE1 MODULE2 ];` - -When `nvimRequireCheck` is not specified, we will search the plugin's directory for lua modules to attempt loading. This quick smoke test can catch obvious dependency errors that might be missed. -The check hook will fail the build if any failures are detected to encourage inspecting the logs to identify potential issues. - -If you would like to only check a specific module, this can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). - -```nix - gitsigns-nvim = super.gitsigns-nvim.overrideAttrs { - dependencies = [ self.plenary-nvim ]; - nvimRequireCheck = "gitsigns"; - }; -``` -Some plugins will have lua modules that require a user configuration to function properly or can contain optional lua modules that we dont want to test requiring. -We can skip specific modules using `nvimSkipModule`. Similar to `nvimRequireCheck`, it accepts a single string or a list of strings. -- `nvimSkipModule = MODULE;` -- `nvimSkipModule = [ MODULE1 MODULE2 ];` - -```nix - asyncrun-vim = super.asyncrun-vim.overrideAttrs { - nvimSkipModule = [ - # vim plugin with optional toggleterm integration - "asyncrun.toggleterm" - "asyncrun.toggleterm2" - ]; - }; -``` - -In rare cases, we might not want to actually test loading lua modules for a plugin. In those cases, we can disable `neovimRequireCheck` with `doCheck = false;`. - -This can be manually added through plugin definition overrides in the [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/overrides.nix). -```nix - vim-test = super.vim-test.overrideAttrs { - # Vim plugin with a test lua file - doCheck = false; - }; -``` ### Plugin optional configuration {#vim-plugin-required-snippet} diff --git a/doc/redirects.json b/doc/redirects.json index d5360283e4613..254e6ceb6fc6e 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -2,6 +2,12 @@ "chap-release-notes": [ "release-notes.html#chap-release-notes" ], + "neovim": [ + "index.html#neovim" + ], + "neovim-custom-configuration": [ + "index.html#neovim-custom-configuration" + ], "nixpkgs-manual": [ "index.html#nixpkgs-manual" ], @@ -3763,7 +3769,8 @@ "vim": [ "index.html#vim" ], - "custom-configuration": [ + "vim-custom-configuration": [ + "index.html#vim-custom-configuration", "index.html#custom-configuration" ], "managing-plugins-with-vim-packages": [ @@ -3772,10 +3779,12 @@ "what-if-your-favourite-vim-plugin-isnt-already-packaged": [ "index.html#what-if-your-favourite-vim-plugin-isnt-already-packaged" ], - "vim-plugin-specificities": [ - "index.html#vim-plugin-specificities" + "neovim-plugin-specificities": [ + "index.html#neovim-plugin-specificities", + "neovim-plugin-specificities#vim-plugin-specificities" ], - "vim-plugin-treesitter": [ + "neovim-plugin-treesitter": [ + "index.html#neovim-plugin-treesitter", "index.html#vim-plugin-treesitter" ], "managing-plugins-with-vim-plug": [