Auto generate docs

Author: github-actions[bot]

doc/lazy-nix-helper.nvim.txt

@@ -1,4 +1,4 @@
-*lazy-nix-helper.nvim.txt*  For Neovim >= 0.9.0? Last change: 2023 December 27
+*lazy-nix-helper.nvim.txt*  For Neovim >= 0.9.0? Last change: 2023 December 29
 
 ==============================================================================
 Table of Contents                     *lazy-nix-helper.nvim-table-of-contents*
@@ -57,10 +57,9 @@ the configuration.
 
 HOW IT WORKS               *lazy-nix-helper.nvim-lazy-nix-helper-how-it-works*
 
-Lazy-Nix-Helper searches the nix store for all installed vim plugins and builds
-a table associating each plugin’s name with its nix store path. The
-`get_plugin_path()` function will return the nix store path corresponding to a
-given plugin name.
+Lazy-Nix-Helper accepts a table mapping plugin names to nix-store plugin paths
+as input. The `get_plugin_path()` function will return the nix store path
+corresponding to a given plugin name if the path exists on the system.
 
 
 REQUIREMENTS               *lazy-nix-helper.nvim-lazy-nix-helper-requirements*
@@ -101,19 +100,23 @@ LAZY-NIX-HELPER CONFIGURATION ~
     {
       lazypath = nil,
       friendly_plugin_names = true,
+      auto_plugin_discovery = false,
+      input_plugin_table = {}
     }
 <
 
-**Config Options** - `lazypath`: the default lazypath. Must be set in plugin
+**Config Options** - `lazypath`: the default lazypath. must be set in plugin
 config - `friendly_plugin_names`: when set to `true` provides less-strict
 plugin name matching for get_plugin_path(): + not case sensitive + treats `-`
 and `_` as identical + add or subtracts `.nvim` from the plugin name as needed
 
-in most cases setting this to true will make updating your configuration much
-easier. if there is a plugin name collision with these rules applied then
+if there is a plugin name collision with these rules applied then
 lazy-nix-helper will thrown an error. in that case you will have to set this
 option to false and match plugin names exactly.
 
+- `auto_plugin_discovery`: when set to `true` enables the automatic plugin discovery originally included in Lazy-Nix-Helper. the automatic plugin discovery is a nix anti-pattern and only works for a subset of nix/nixos use cases and config arrangements. this option has been left in place to let early adopters of Lazy-Nix-Helper keep their original configuration, but it should be set to `false` for all new configurations
+- `input_plugin_table`: the plugin table mapping plugin names to plugin paths generated by your nix config. instructions for generating this table are provided in the NixOS Configuration section
+
 **Lazy-Nix-Helper’s own Nix Store Path**
 
 The nix store path for the Lazy-Nix-Helper plugin itself cannot be provided by
@@ -170,8 +173,14 @@ Lazy-Nix-Helper `setup()` function - set the lazypath using Lazy-Nix-Helper
 Update the configuration as follows:
 
 >lua
-    -- See the NixOS Configuration section for more details
+    -- THIS PLUGIN LIST SHOULD BE GENERATED BY YOUR NIX CONFIG. See the NixOS Configuration section for more details on plugins table and lazy_nix_helper_path
+    local plugins = {
+     ["plugin-name.nvim"] = "nix/store/hash1234-vimplugin-plugin-name.nvim",
+     ...
+    }
+    
     local lazy_nix_helper_path = <lazy_nix_helper/nix/store/path>
+    
     -- if we are not on a nix-based system, bootstrap lazy_nix_helper in the same way lazy is bootstrapped
     if not vim.loop.fs_stat(lazy_nix_helper_path) then
       lazy_nix_helper_path = vim.fn.stdpath("data") .. "/lazy_nix_helper/lazy_nix_helper.nvim"
@@ -191,7 +200,7 @@ Update the configuration as follows:
 
     -- call the Lazy-Nix-Helper setup function. pass a default lazypath for non-nix systems as an argument
     local non_nix_lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
-    require("lazy-nix-helper").setup({ lazypath = non_nix_lazypath })
+    require("lazy-nix-helper").setup({ lazypath = non_nix_lazypath, input_plugin_table = plugins })
 
     -- get the lazypath from Lazy-Nix-Helper
     local lazypath = require("lazy-nix-helper").lazypath()
@@ -344,7 +353,8 @@ instructions for additional information
 https://github.com/NixOS/nixpkgs/blob/master/doc/languages-frameworks/vim.section.md#what-if-your-favourite-vim-plugin-isnt-already-packaged-what-if-your-favourite-vim-plugin-isnt-already-packaged
 2. Put your existing `init.lua` within `programs.neovim.extraLuaConfig`. 3.
 Update your `init.lua` to provide the nix store path of Lazy-Nix-Helper 4.
-Include the rest of your config files with `xdg.configFile`.
+Generate the plugins table 5. Include the rest of your config files with
+`xdg.configFile`.
 
 `neovim.nix` module:
 
@@ -362,6 +372,15 @@ Include the rest of your config files with `xdg.configFile`.
         };
       };
 
+      sanitizePluginName = input:
+      let
+        name = lib.strings.getName input;
+        intermediate = lib.strings.removePrefix "vimplugin-" name;
+        result = lib.strings.removePrefix "lua5.1-" intermediate;
+      in result;
+    
+      pluginList = plugins: lib.strings.concatMapStrings (plugin: "  [\"${sanitizePluginName plugin.name}\"] = \"${plugin.outPath}\",\n") plugins;
+    
     in
       {
         xdg.configFile."nvim/lua" = {
@@ -381,6 +400,9 @@ Include the rest of your config files with `xdg.configFile`.
               <other plugins>
           ];
           extraLuaConfig = ''
+            local plugins = {
+            ${pluginList config.programs.neovim.plugins}
+            }
             local lazy_nix_helper_path = "${lazy-nix-helper-nvim}"
             if not vim.loop.fs_stat(lazy_nix_helper_path) then
               lazy_nix_helper_path = vim.fn.stdpath("data") .. "/lazy_nix_helper/lazy_nix_helper.nvim"
@@ -398,9 +420,9 @@ Include the rest of your config files with `xdg.configFile`.
             -- add the Lazy Nix Helper plugin to the vim runtime
             vim.opt.rtp:prepend(lazy_nix_helper_path)
 
-            -- call the Lazy Nix Helper setup function. pass a default lazypath for non-nix systems as an argument
+            -- call the Lazy Nix Helper setup function
             local non_nix_lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
-            local lazy_nix_helper_opts = { lazypath = non_nix_lazypath }
+            local lazy_nix_helper_opts = { lazypath = non_nix_lazypath, input_plugin_table = plugins }
             require("lazy-nix-helper").setup(lazy_nix_helper_opts)
 
             -- get the lazypath from Lazy Nix Helper
@@ -434,27 +456,27 @@ system.
 
 KNOWN LIMITATIONS     *lazy-nix-helper.nvim-lazy-nix-helper-known-limitations*
 
-Lazy-Nix-Helper can’t currently find plugins installed by Nix on non-NixOS
-platforms.
-
-Lazy-Nix-Helper’s plugin discovery mechanism searches the current system’s
-installed packages for packages prefixed with `vimplugin` or `lua5.1`. As of
-2023-12-27 these are the only two prefixes used by the vimPlugin packageset in
-the unstable branch of nixpkgs. This works for now, but may break if a new
-prefix is added or existing prefixes are changed. It would be best to allow a
-list of plugin paths to be passed into the `setup()` function so that the nix
-store paths of neovim plugins could be provided declaratively by the NixOS
-config.
+I have not tested Lazy-Nix-Helper with: - Nix-installed neovim/plugins on a
+non-NixOS system - Nix-darwin
 
 
 ALTERNATIVES               *lazy-nix-helper.nvim-lazy-nix-helper-alternatives*
 
 Besides Lazy-Nix-Helper there are other tools and strategies you might choose
 to manage your neovim configuration under NixOS:
 
+
+NIX-BASED SOLUTIONS ~
+
 - Home-Manager <https://nix-community.github.io/home-manager/> provides options for installing and configuring neovim plugins
 - NixVim <https://github.com/nix-community/nixvim/> is a neovim distribution built around Nix modules. It provides nix-style configuration options for every neovim configuration option as well as options for many plugins
-- Using your existing config as-is. Depending on how complicated your current config is and what it includes, you may be able to copy your dotfiles and have everything work out of the box. The main downside is that you lose the reproducability benefits of nix by using a different package manager
+
+### Prebuilt flakes TODO: include some examples
+
+### Non-nix - Using your existing config as-is. Depending on how complicated
+your current config is and what it includes, you may be able to copy your
+dotfiles and have everything work out of the box. The main downside is that you
+lose the reproducability benefits of nix by using a different package manager
 
 
 TROUBLESHOOTING         *lazy-nix-helper.nvim-lazy-nix-helper-troubleshooting*
@@ -466,23 +488,29 @@ Use the `:Lazy` command to open the Lazy dashboard. The source directory is
 listed for each plugin
 
 
-HOW DO I CHECK WHICH PATH LAZY-NIX-HELPER HAS FOUND FOR A PLUGIN? ~
+HOW DO I CHECK THE PLUGIN LIST THAT WAS SUPPLIED TO LAZY-NIX-HELPER? ~
 
-Run the `get_plugin_path` function manually: `:lua
-print(require("lazy-nix-helper").get_plugin_path("<plugin-name>"))`
+Run the `list_input_plugins` function manually: `lua
+require("lazy-nix-helper").list_input_plugins()`
 
 
-HOW DO I CHECK ALL OF THE PLUGINS THAT LAZY-NIX-HELPER HAS FOUND? ~
+HOW DO I CHECK WHICH PLUGINS WERE FOUND ON THE SYSTEM BY LAZY-NIX-HELPER? ~
 
 Run the `list_discovered_plugins` function manually: `lua
 require("lazy-nix-helper").list_discovered_plugins()`
 
 
+HOW DO I CHECK WHICH PATH LAZY-NIX-HELPER HAS FOUND FOR A PLUGIN? ~
+
+Run the `get_plugin_path` function manually: `:lua
+print(require("lazy-nix-helper").get_plugin_path("<plugin-name>"))`
+
+
 I DON’T THINK LAZY-NIX-HELPER IS CORRECTLY DETECTING WHEN I’M ON NIXOS ~
 
 Run the `print_environment_info` function manually to see: - if Lazy-Nix-Helper
 thinks you’re on NixOS or not - if Lazy-Nix-Helper thinks nix-store is
-installed or not
+installed or not (only relevant for legacy automatic plugin discovery)
 
 `lua require("lazy-nix-helper").print_environment_info()`