Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: give neovim its own neovim.section.md #373090

Merged
merged 1 commit into from
Jan 12, 2025
+123 −104
Merged

doc: give neovim its own neovim.section.md #373090

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/languages-frameworks/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,4 +96,5 @@ swift.section.md
tcl.section.md
texlive.section.md
vim.section.md
neovim.section.md
```
107 changes: 107 additions & 0 deletions doc/languages-frameworks/neovim.section.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`neovimRequireCheck` is a simple test which checks if Neovim can requires lua modules without errors. This is often enough to catch missing dependencies.
`neovimRequireCheck` is a simple test which checks if Neovim can load a plugin's lua modules without errors. This is often enough to catch missing dependencies.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer the "require" mention that makes it clearer for the initiated (which this subsection is for).


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;`.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Doing so will also prevent the plugin's test suite from running (if present).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@khaneliman is there any instance of us disabling doCheck just because of neovimRequireCheck ? If not let's delete this part.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also there is a mix of neovimRequireCheck and nvimRequireCheck. Maybe you want to talk about neovimRequireCheckHook but it can be fixed in a separate PR.

Copy link
Contributor

@khaneliman khaneliman Jan 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most other language/framework sections contain some mention about the usage of doCheck = false; to skip the check phase. This is just an explanation of why you might want to use it. So I'd rather keep it but maybe update the example with some more accurate.

  supermaven-nvim = super.supermaven-nvim.overrideAttrs {
    # TODO: handle supermaven binary
    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;
};
```
102 changes: 2 additions & 100 deletions doc/languages-frameworks/vim.section.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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:

Expand All @@ -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}

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}

Expand Down
17 changes: 13 additions & 4 deletions doc/redirects.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
],
Expand Down Expand Up @@ -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": [
Expand All @@ -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"
Copy link
Contributor

@fricklerhandwerk fricklerhandwerk Jan 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably have been index.html#vim-plugin-specificities?

But great to see that @GetPsyched's work is useful to avoid documentation falling apart 😄

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe ? Because I had seen the PR about the redirection and all I had an idea of what was going on, otherwise I think the feedback would have surprised me more. I understand the idea behind the redirects but as a maintainer it's one additional hurdle to contribute to the doc and the UX frustrated me quite a bit. I spent more time trying to work out the redirections rather than the doc changes. Note that I contribute to the doc reluctantly as a last resort so I am already grumpy by then ^^'
First I think the errors should give a bit of context otherwise these errors popup without explanation.
I dont know how hard that is but if we could use redirects.jsonc instead of redirects.json, one could document the format a bit at the top of the file and document the redirects later (it might not matter much though).
the redirects executable differentiate between rename and moved content but it seemed articial. I believe this are no checks on the input arguments ? several times I ended up with wrong anchors or duplicates.
Is there any other possible value for path than "index.html" ? else we could default to that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback! And sorry that the experience was frustrating. Good point about input validation! The format is documented in the source code for the tool dealing with it, but it sounds reasonable to indeed document it in place. rename and move are different because the ultimate goal is to be able to change the page to where content is rendered, which is not implemented yet.

],
"vim-plugin-treesitter": [
"neovim-plugin-treesitter": [
"index.html#neovim-plugin-treesitter",
"index.html#vim-plugin-treesitter"
],
"managing-plugins-with-vim-plug": [
Expand Down