NixVim improvents!

[pta2002]

This serves as a tracking issue for all planned improvements to be made to NixVim.

Documentation

• Better, per-module documentation
• Documentation search
• Document every option

Features

• Support package option for every plugin (Add package options for plugins #58)
• Support defining keybinds in every plugin
• Support pinning treesitter versions (to fix bugs with the invalid nodes)
• Support which-key - can use the maps option to automatically populate it
• Support autocommands (initially, just extraConfigLua and extraConfigVim are fine, but I'd really like to be able to set per-plugin options for this eventually)
• Use vim.keybind.set to define mappings
• Allow lazy-loading of plugins ([Feature] Lazy loading #421)
• In-editor "enabled options" and "documentation" #1706
• Automated testing

[GaetanLepage]

#115 solves the

• Use vim.keybind.set to define mappings

item.

[pta2002]

Oops, thanks for reminding me

[Alexnortung]

What about automated tests, just to make sure that nixvim can build the configuration for all plugins. This would require something like github actions (or circleci which i can see is used) to run the tests. And then a simple test configuration for each module. The test files could just be called something like pluginName.test.nix.

The tests can also be run by contributors to verify that the module works as expected.

I think this would greatly improve the review process and make it easier for contributors to catch their errors.

@pta2002

[Alexnortung]

Another improvement could be adding something like devenv and adding a pre commit hook to a formatter (rnix-lsp for example), so that it is okay if we forget to format before committing.

[pta2002]

What about automated tests, just to make sure that nixvim can build the configuration for all plugins. This would require something like github actions (or circleci which i can see is used) to run the tests. And then a simple test configuration for each module. The test files could just be called something like pluginName.test.nix.

I quite like the idea of automated tests. I had thought about it, but I haven't really figured out how to do it. I assume there are ways though, will have to look into it. Will add to the list!

[pta2002]

I also really like the idea of the pre-commit hook! Will look into devenv.

[MattSturgeon]

Any thoughts on how lazy loading could be implemented?

[GaetanLepage]

Any thoughts on how lazy loading could be implemented?

Hmm I am not really sure. Obviously, we could look at how lazy nvim does it and try to replicate the same.
Feel free to hack something and try. I will happily review your PR :)

[GaetanLepage]

• Support which-key - can use the maps option to automatically populate it
• Support autocommands (initially, just extraConfigLua and extraConfigVim are fine, but I'd really like to be able to set per plugin options for this eventually)

Aren't those two now solved ?
We have a module for autocommands and it is possible to add a description to each mapping that which-key can use.
@pta2002 was that what you were thinking of when writing those objectives ?

[pta2002]

Oh yes they are done! will mark them as done, kinda forgot about this issue

[pta2002]

Any thoughts on how lazy loading could be implemented?

With @GaetanLepage on this one - basically just look at how lazy nvim does it, and implement that. It's not necessarily simple but it shouldn't be too hard.

[MattSturgeon]

I'm probably not the best person to work on this as I'm fairly new to nix and haven't messed much with lua plugins either. I also don't have much time to dedicate atm. But I've had a quick look through lazy.nvim...

Lazy.nvim actually completely disables vim's plugin loading system and re-implements it itself to gain full control of the process.

I don't think disabling NeoVim's plugin loading is neccessary to lazy load plugins if we can avoid adding them to the runtimepath. If we instead allow neovim to load plugins in the runtimepath as-per normal, we would just need to ensure that any packages marked "lazy" are not added to the rtp by nix's neovim-wrapper.

If we can manage that, then NixVim just needs to add handlers for each lazy-loaded plugin's keybinds/commands/trigger events. These handlers would add the plugin to the rtp and source
files in the relevant directories.

Does neovim-wrapper currently support not adding a plugin to the runtimepath, or would that option need to be implemented upstream?

Overview of lazy.nvim's plugin loading system:

lazy.nvim's entrypoint is the M.setup() function in /lua/init.lua.
From setup() it some sanity checks and sets up caching, then gets into the meat of things loading the config, setting up the loader (Loader.setup()) and finally loading non-lazy plugins (Loader.startup()).

In Config.setup(), vim's plugin loading is disabled using vim.go.loadplugins=false
which gives lazy.nvim full control to load things how it likes and even blacklist builtin plugins such as tutorial to gain a little performance.

Loader.setup()
starts by copying the list of disabled plugins (usually used to prevent loading builtin plugins such as tutorial), then it calls Plugin.load()
which parses the config's plugin list.

Finally, Loader.setup() calls Handler.setup()
which creates event handlers for any keybinds/events/commands/etc defined in the config's plugin list. Lazy plugins are loaded later by these event handlers.

Loader.startup()
initially loads /filetype.lua for compatibility reasons, then it backs up the runtimepath, calls any configured init handlers, finally it loads the non-lazy plugins.

First the configured plugins are loaded, looping over Loader.get_start_plugins() and passing each to Loader.load(). This mutates the runtimepath, hence why the original was copied earlier.

Next Loader.startup() loops over everything in the origional runtimepath (mainly builtin plugins), passing each to Loader.packadd() which sources the rumtime.

Finally, Loader.startup() loops over the new runtimepath, and sources everything in an /after directory.

[GaetanLepage]

Wow ! Thank you very much @MattSturgeon for this detailed description of the working of lazy.nvim.
I have never used it myself so this stuff is unfamiliar to me.
I think that lazy loading support would be a great addition to nixvim.
However, given your description, it seems to imply some substantial development effort.
Our approach would probably be different than the one of lazy.nvim as we can perform operations at build time when generating the lua code.

I am opening a new issue to track this development: #421
I suggest to keep this discussion there.

[Bodleum]

Could we also look into better lua integration?
Writing lua code as a nix string is far from ideal, and makes even a simple missing comma much harder to catch.

I'm not sure if this is even possible in nix but directly writing lua would be ideal.

[MattSturgeon]

@Bodleum I don't think this is something nixvim itself can handle, but if you are using nvim-treesitter to highlight your nix files, you can mark strings as lua by annotating them with a comment:

someValue = /* lua */ ''
  function() --[[ lua code ]] end
'';

See nvim-treesitter/nvim-treesitter#4658

[gshpychka]

@Bodleum I don't think this is something nixvim itself can handle, but if you are using nvim-treesitter to highlight your nix files, you can mark strings as lua by annotating them with a comment:

someValue = /* lua */ ''
  function() --[[ lua code ]] end
'';

See nvim-treesitter/nvim-treesitter#4658

This would get you highlighting, but not all the LSP niceties.

[Bodleum]

What if there were two ways of configuring a plugin with nixvim:

1. The standard nixvim way that is in use right now.
2. Nixvim reads a lua file with the desired configuration.

Each package could come with an option to configure with lua, which you can pass in a lua file path and nixvim will use the configuration there to configure the plugin. I'm envisaging something like how lazy.nvim does it, A table with the plugin name, opts, config, etc. Maybe even compatibility is possible? I think this would reduce the "double-configuring" feel as well.

This is something I'd be willing and keen to work on, with a bit of assistance!

[traxys]

You could always use builtins.readFile to achieve this

[Eveeifyeve]

What if there were two ways of configuring a plugin with nixvim:

1. The standard nixvim way that is in use right now.

2. Nixvim reads a lua file with the desired configuration.

Each package could come with an option to configure with lua, which you can pass in a lua file path and nixvim will use the configuration there to configure the plugin. I'm envisaging something like how lazy.nvim does it, A table with the plugin name, opts, config, etc. Maybe even compatibility is possible? I think this would reduce the "double-configuring" feel as well.

This is something I'd be willing and keen to work on, with a bit of assistance!

There is kinda allready a way using extraluaconfig by listing the file by using the builtin.readFile from nix to output the file.

[Eveeifyeve]

Hey i am pretty interested on the documentation command in vim you just do vim,command so what if nixvim had a command that loads a man page like how neovim does it already.

[MattSturgeon]

There's not many outstanding items on this issue, and its scope is rather broad. I think we can close this now?

I'm not sure "support defining keybinds in every plugin" is an achievable goal.

"Better, per-module documentation" is rather vague. Is this meaning the platform wrapper modules? How do we define better?

"Allow lazy-loading of plugins" is already tracked in #421

"Have some form of in-editor documentation (e.g., a :NixVim command which shows a page showing currently enabled options and documentation)" has been opened as #1706

All other items are marked as complete.