docs: better docs

README.md

@@ -5,35 +5,84 @@ A collection of small QoL plugins for Neovim.
 > [!CAUTION]
 > Do **NOT** use this for now, it's still in development.
 
-## Todo
+## ⚡️ Requirements
 
-- [ ] docs :)
-- [x] float => win
-- [x] win views
-- [ ] cowboy
-- [x] notifier
-- [x] docgen
-- [x] plugin
-- [x] notify module
-- [x] overload docgen
-- [x] bigfile `BufReadPre`
-- [x] bufdelete
-- [x] statuscolumn
-- [x] words `LspAttach`
-- [x] quickfile `BufReadPost`
-- [x] rename
-- [x] terminal
-- [x] float
-- [x] lazygit
-- [x] git
-- [x] gitbrowse
-- [x] toggle
+- **Neovim** >= 0.9.4
+- for proper icons support:
+  - [mini.icons](https://github.com/echasnovski/mini.icons) _(optional)_
+  - [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) _(optional)_
+  - a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_**
 
-### Maybe
+## 📦 Installation
 
-- [ ] zen
-- [ ] lsp
-- [ ] root
+Install the plugin with your package manager:
+
+### [lazy.nvim](https://github.com/folke/lazy.nvim)
+
+> [!important]
+> A couple of plugins **require** `snacks.nvim` to be set-up early.
+> Setup only sets up some autocmds and does not load any plugins.
+> Check the [code](https://github.com/folke/snacks.nvim/blob/main/lua/snacks/init.lua) to see exactly what is being set up.
+
+> [!tip]
+> If you don't need these plugins, you can disable them, or skip `setup` alltogether.
+
+```lua
+{
+  "folke/snacks.nvim",
+  priority = 1000,
+  lazy = false,
+  opts = {
+    -- your configuration comes here
+    -- or leave it empty to use the default settings
+    -- refer to the configuration section below
+  },
+  keys = {
+    {
+      "<leader>?",
+      function()
+        require("which-key").show({ global = false })
+      end,
+      desc = "Buffer Local Keymaps (which-key)",
+    },
+  },
+}
+```
+
+## ⚙️ Configuration
+
+Please refer to the readme of each plugin for their specific configuration.
+
+<details><summary>Default Options</summary>
+
+<!-- config:start -->
+
+```lua
+---@class snacks.Config
+---@field bigfile? snacks.bigfile.Config | { enabled: boolean }
+---@field gitbrowse? snacks.gitbrowse.Config
+---@field lazygit? snacks.lazygit.Config
+---@field notifier? snacks.notifier.Config | { enabled: boolean }
+---@field quickfile? { enabled: boolean }
+---@field statuscolumn? snacks.statuscolumn.Config  | { enabled: boolean }
+---@field terminal? snacks.terminal.Config
+---@field toggle? snacks.toggle.Config
+---@field views? table<string, snacks.win.Config>
+---@field win? snacks.win.Config
+---@field words? snacks.words.Config
+{
+  views = {},
+  bigfile = { enabled = true },
+  notifier = { enabled = true },
+  quickfile = { enabled = true },
+  statuscolumn = { enabled = true },
+  words = { enabled = true },
+}
+```
+
+<!-- config:end -->
+
+</details>
 
 ## 📦 Snacks
 

doc/snacks-bigfile.txt

@@ -13,12 +13,13 @@ Table of Contents                           *snacks-bigfile-table-of-contents*
 >lua
     ---@class snacks.bigfile.Config
     {
+      notify = true,
       size = 1.5 * 1024 * 1024, -- 1.5MB
-      ---@param ev {buf: number, ft:string}
-      behave = function(ev)
+      ---@param ctx {buf: number, ft:string}
+      setup = function(ctx)
         vim.b.minianimate_disable = true
         vim.schedule(function()
-          vim.bo[ev.buf].syntax = ev.ft
+          vim.bo[ctx.buf].syntax = ctx.ft
         end)
       end,
     }

doc/snacks-init.txt

@@ -3,31 +3,60 @@
 ==============================================================================
 Table of Contents                              *snacks-init-table-of-contents*
 
-1. Module                                                 |snacks-init-module|
+1. Config                                                 |snacks-init-config|
+2. Module                                                 |snacks-init-module|
   - Snacks.config.get()               |snacks-init-module-snacks.config.get()|
   - Snacks.config.view()             |snacks-init-module-snacks.config.view()|
   - Snacks.setup()                         |snacks-init-module-snacks.setup()|
 
 ==============================================================================
-1. Module                                                 *snacks-init-module*
+1. Config                                                 *snacks-init-config*
+
+>lua
+    ---@class snacks.Config
+    ---@field bigfile? snacks.bigfile.Config | { enabled: boolean }
+    ---@field gitbrowse? snacks.gitbrowse.Config
+    ---@field lazygit? snacks.lazygit.Config
+    ---@field notifier? snacks.notifier.Config | { enabled: boolean }
+    ---@field quickfile? { enabled: boolean }
+    ---@field statuscolumn? snacks.statuscolumn.Config  | { enabled: boolean }
+    ---@field terminal? snacks.terminal.Config
+    ---@field toggle? snacks.toggle.Config
+    ---@field views? table<string, snacks.win.Config>
+    ---@field win? snacks.win.Config
+    ---@field words? snacks.words.Config
+    {
+      views = {},
+      bigfile = { enabled = true },
+      notifier = { enabled = true },
+      quickfile = { enabled = true },
+      statuscolumn = { enabled = true },
+      words = { enabled = true },
+    }
+<
+
+
+==============================================================================
+2. Module                                                 *snacks-init-module*
 
 >lua
     ---@class Snacks
+    ---@field config snacks.config
     ---@field bigfile snacks.bigfile
     ---@field bufdelete snacks.bufdelete
-    ---@field quickfile snacks.quickfile
-    ---@field statuscolumn snacks.statuscolumn
-    ---@field words snacks.words
-    ---@field rename snacks.rename
-    ---@field win snacks.win
-    ---@field terminal snacks.terminal
-    ---@field lazygit snacks.lazygit
+    ---@field debug snacks.debug
     ---@field git snacks.git
     ---@field gitbrowse snacks.gitbrowse
-    ---@field notify snacks.notify
-    ---@field debug snacks.debug
-    ---@field toggle snacks.toggle
+    ---@field lazygit snacks.lazygit
     ---@field notifier snacks.notifier
+    ---@field notify snacks.notify
+    ---@field quickfile snacks.quickfile
+    ---@field rename snacks.rename
+    ---@field statuscolumn snacks.statuscolumn
+    ---@field terminal snacks.terminal
+    ---@field toggle snacks.toggle
+    ---@field win snacks.win
+    ---@field words snacks.words
     Snacks = {}
 <
 
@@ -58,7 +87,7 @@ Register a new window view config.
 SNACKS.SETUP()                             *snacks-init-module-snacks.setup()*
 
 >lua
-    ---@param opts snacks.Opts?
+    ---@param opts snacks.Config?
     Snacks.setup(opts)
 <
 

docs/bigfile.md

@@ -7,12 +7,13 @@
 ```lua
 ---@class snacks.bigfile.Config
 {
+  notify = true,
   size = 1.5 * 1024 * 1024, -- 1.5MB
-  ---@param ev {buf: number, ft:string}
-  behave = function(ev)
+  ---@param ctx {buf: number, ft:string}
+  setup = function(ctx)
     vim.b.minianimate_disable = true
     vim.schedule(function()
-      vim.bo[ev.buf].syntax = ev.ft
+      vim.bo[ctx.buf].syntax = ctx.ft
     end)
   end,
 }

docs/init.md

@@ -2,25 +2,51 @@
 
 <!-- docgen -->
 
+## ⚙️ Config
+
+```lua
+---@class snacks.Config
+---@field bigfile? snacks.bigfile.Config | { enabled: boolean }
+---@field gitbrowse? snacks.gitbrowse.Config
+---@field lazygit? snacks.lazygit.Config
+---@field notifier? snacks.notifier.Config | { enabled: boolean }
+---@field quickfile? { enabled: boolean }
+---@field statuscolumn? snacks.statuscolumn.Config  | { enabled: boolean }
+---@field terminal? snacks.terminal.Config
+---@field toggle? snacks.toggle.Config
+---@field views? table<string, snacks.win.Config>
+---@field win? snacks.win.Config
+---@field words? snacks.words.Config
+{
+  views = {},
+  bigfile = { enabled = true },
+  notifier = { enabled = true },
+  quickfile = { enabled = true },
+  statuscolumn = { enabled = true },
+  words = { enabled = true },
+}
+```
+
 ## 📦 Module
 
 ```lua
 ---@class Snacks
+---@field config snacks.config
 ---@field bigfile snacks.bigfile
 ---@field bufdelete snacks.bufdelete
----@field quickfile snacks.quickfile
----@field statuscolumn snacks.statuscolumn
----@field words snacks.words
----@field rename snacks.rename
----@field win snacks.win
----@field terminal snacks.terminal
----@field lazygit snacks.lazygit
+---@field debug snacks.debug
 ---@field git snacks.git
 ---@field gitbrowse snacks.gitbrowse
----@field notify snacks.notify
----@field debug snacks.debug
----@field toggle snacks.toggle
+---@field lazygit snacks.lazygit
 ---@field notifier snacks.notifier
+---@field notify snacks.notify
+---@field quickfile snacks.quickfile
+---@field rename snacks.rename
+---@field statuscolumn snacks.statuscolumn
+---@field terminal snacks.terminal
+---@field toggle snacks.toggle
+---@field win snacks.win
+---@field words snacks.words
 Snacks = {}
 ```
 
@@ -48,6 +74,6 @@ Snacks.config.view(name, defaults)
 ### `Snacks.setup()`
 
 ```lua
----@param opts snacks.Opts?
+---@param opts snacks.Config?
 Snacks.setup(opts)
 ```

lua/snacks/docs.lua

@@ -4,6 +4,7 @@ local M = {}
 function M.extract(lines)
   local code = table.concat(lines, "\n")
   local config = code:match("\n(%-%-%- ?@class snacks%.%w+%.Config.-\n})")
+  config = config or code:match("\n(%-%-%- ?@class snacks%.Config.-\n})")
   local mod = code:match("(%-%-%-.*\n)local M =")
   local comments = {} ---@type string[]
   local types = {} ---@type string[]
@@ -36,7 +37,7 @@ function M.extract(lines)
 
   ---@class snacks.docs.Info
   local ret = {
-    config = config and config:gsub("local defaults = ", "") or nil,
+    config = config and config:gsub("local defaults = ", ""):gsub("local config = ", "") or nil,
     mod = mod,
     methods = methods,
     types = types,
@@ -44,6 +45,18 @@ function M.extract(lines)
   return ret
 end
 
+---@param tag string
+---@param readme string
+---@param content string
+function M.replace(tag, readme, content)
+  content = vim.trim(content)
+  local pattern = "(<%!%-%- " .. tag .. ":start %-%->).*(<%!%-%- " .. tag .. ":end %-%->)"
+  if not readme:find(pattern) then
+    error("tag " .. tag .. " not found")
+  end
+  return readme:gsub(pattern, "%1\n\n" .. content .. "\n\n%2")
+end
+
 function M.md(str)
   local comments = {} ---@type string[]
   local lines = vim.split(str, "\n", { plain = true })
@@ -173,6 +186,11 @@ function M.build()
       local lines = vim.fn.readfile(path)
       local info = M.extract(lines)
       M.write(name, M.render(name, info))
+      if name == "init" then
+        local readme = table.concat(vim.fn.readfile("README.md"), "\n")
+        readme = M.replace("config", readme, M.md(info.config))
+        vim.fn.writefile(vim.split(readme, "\n"), "README.md")
+      end
     end
   end
   vim.cmd.checktime()

lua/snacks/init.lua

@@ -1,19 +1,20 @@
 ---@class Snacks
+---@field config snacks.config
 ---@field bigfile snacks.bigfile
 ---@field bufdelete snacks.bufdelete
----@field quickfile snacks.quickfile
----@field statuscolumn snacks.statuscolumn
----@field words snacks.words
----@field rename snacks.rename
----@field win snacks.win
----@field terminal snacks.terminal
----@field lazygit snacks.lazygit
+---@field debug snacks.debug
 ---@field git snacks.git
 ---@field gitbrowse snacks.gitbrowse
----@field notify snacks.notify
----@field debug snacks.debug
----@field toggle snacks.toggle
+---@field lazygit snacks.lazygit
 ---@field notifier snacks.notifier
+---@field notify snacks.notify
+---@field quickfile snacks.quickfile
+---@field rename snacks.rename
+---@field statuscolumn snacks.statuscolumn
+---@field terminal snacks.terminal
+---@field toggle snacks.toggle
+---@field win snacks.win
+---@field words snacks.words
 local M = {}
 
 setmetatable(M, {
@@ -26,33 +27,29 @@ setmetatable(M, {
 
 _G.Snacks = M
 
----@class snacks.Opts
----@field bigfile snacks.bigfile.Config | { enabled: boolean }
----@field quickfile { enabled: boolean }
----@field statuscolumn snacks.statuscolumn.Config  | { enabled: boolean }
----@field words snacks.words.Config
----@field win snacks.win.Config
----@field terminal snacks.terminal.Config
----@field lazygit snacks.lazygit.Config
----@field gitbrowse snacks.gitbrowse.Config
----@field views table<string, snacks.win.Config>
----@field notifier snacks.notifier.Config | { enabled: boolean }
----@field toggle snacks.toggle.Config
+---@class snacks.Config
+---@field bigfile? snacks.bigfile.Config | { enabled: boolean }
+---@field gitbrowse? snacks.gitbrowse.Config
+---@field lazygit? snacks.lazygit.Config
+---@field notifier? snacks.notifier.Config | { enabled: boolean }
+---@field quickfile? { enabled: boolean }
+---@field statuscolumn? snacks.statuscolumn.Config  | { enabled: boolean }
+---@field terminal? snacks.terminal.Config
+---@field toggle? snacks.toggle.Config
+---@field views? table<string, snacks.win.Config>
+---@field win? snacks.win.Config
+---@field words? snacks.words.Config
 local config = {
+  views = {},
   bigfile = { enabled = true },
+  notifier = { enabled = true },
   quickfile = { enabled = true },
   statuscolumn = { enabled = true },
   words = { enabled = true },
-  views = {},
-  notifier = { enabled = true },
 }
 
----@class snacks.Config: snacks.Opts
-M.config = setmetatable({}, {
-  __index = function(_, k)
-    return config[k]
-  end,
-})
+---@class snacks.config: snacks.Config
+M.config = setmetatable({}, { __index = config })
 
 ---@generic T: table
 ---@param snack string
@@ -77,7 +74,7 @@ function M.config.view(name, defaults)
   config.views[name] = vim.tbl_deep_extend("force", vim.deepcopy(defaults), config.views[name] or {})
 end
 
----@param opts snacks.Opts?
+---@param opts snacks.Config?
 function M.setup(opts)
   config = vim.tbl_deep_extend("force", config, opts or {})
 
@@ -106,6 +103,7 @@ function M.setup(opts)
   if M.config.statuscolumn.enabled then
     vim.o.statuscolumn = [[%!v:lua.require'snacks.statuscolumn'.get()]]
   end
+
   if M.config.notifier.enabled then
     vim.notify = function(msg, level, o)
       return Snacks.notifier:notify(msg, level, o)

scripts/docs

@@ -1,5 +1,7 @@
 #!/bin/env bash
 
+set -e
+
 nvim -u tests/minit.lua --headless +'lua require("snacks.docs").build()' +qa
 
 echo -e "\n\nGenerating Vim Help"