docs: add vimdoc help file and README cleanup

.github/workflows/panvimdoc.yml

@@ -0,0 +1,34 @@
+name: panvimdoc
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - README.md
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: generate vimdoc
+    steps:
+      - uses: actions/checkout@v4
+      - name: generate vimdoc
+        uses: kdheepak/panvimdoc@v5.0.0
+        with:
+          vimdoc: bluloco
+          description: "A fancy and sophisticated designer neovim theme"
+          version: "Neovim"
+          demojify: true
+          treesitter: true
+          ignorerawblocks: true
+          shiftheadinglevelby: -1
+      - name: add spacing after callouts
+        run: perl -0pi -e 's/(^  (?:Notes?|Warning|Deprecated):.*(?:\n  .*)*)\n(?=\S)/$1\n\n/gmi' doc/bluloco.txt
+      - name: generate help tags
+        run: vim -es -u NONE -c "helptags doc" -c "qa"
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore(docs): auto generate vimdoc"

README.md

@@ -1,21 +1,29 @@
+<!-- panvimdoc-ignore-start -->
+
 ![banner-light](./screenshots/banner-light.svg#gh-light-mode-only)
 ![banner-dark](./screenshots/banner-dark.svg#gh-dark-mode-only)
 
+<!-- panvimdoc-ignore-end -->
+
 # Bluloco.nvim
 
+## Overview
+
 A fancy and sophisticated designer neovim theme built with [lush.nvim](https://github.com/rktjmp/lush.nvim).
 It features a much more comprehensive usage of syntax scopes and color
 consistency, with due regards to aesthetics, contrast and readability.
 There is a light and dark variant.
-Most popular plugins are also supported, see [Plugins](#plugins)
+Most popular plugins are also supported, see [Plugins](#plugin-support)
 
 This theme also works very good with blue light filters like Apple's _Nightshift Mode_ or _f.lux_.
 
 This is a port of the popular Visual Studio Code Themes
 [Bluloco Light](https://github.com/uloco/theme-bluloco-light) and
 [Bluloco Dark](https://github.com/uloco/theme-bluloco-dark)
 
-### Support
+<!-- panvimdoc-ignore-start -->
+
+## Support
 
 If you like using this, please consider donating a little bit. It takes a lot of time to keep this updated with neovim and plugin updates.
 I want to keep bluloco a great experience for everybody and your help would be immensely motivating to keep me doing this. :)
@@ -30,65 +38,20 @@ I want to keep bluloco a great experience for everybody and your help would be i
 
 ![light](./screenshots/light.png)
 
+<!-- panvimdoc-ignore-end -->
+
 ## Features
 
 - Auto switching light & dark style
 - Configurable _transparency_ and _italics_
 - Exhaustive plugin support
 - Written in lua
 
-## Plugins
-
-Currently supported (aka. tested) plugins:
-
-- [treesitter](https://github.com/nvim-treesitter/nvim-treesitter)
-- [hlargs](https://github.com/m-demare/hlargs.nvim)
-- [alpha-nvim](https://github.com/goolord/alpha-nvim)
-- [nvim-notify](https://github.com/rcarriga/nvim-notify)
-- [mason.nvim](https://github.com/williamboman/mason.nvim)
-- [nvim-cursorword](https://github.com/xiyaowong/nvim-cursorword)
-- [vim-illuminate](https://github.com/RRethy/vim-illuminate)
-- [nvim-scrollbar](https://github.com/petertriho/nvim-scrollbar)
-- [lualine.nvim](https://github.com/hoob3rt/lualine.nvim)
-- [barbar.nvim](https://github.com/romgrk/barbar.nvim)
-- [nvim-bufferline.lua](https://github.com/akinsho/nvim-bufferline.lua)
-- [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim)
-- [neogit](https://github.com/TimUntersberger/neogit)
-- [diffview.nvim](https://github.com/sindrets/diffview.nvim)
-- [codediff.nvim](https://github.com/esmuellert/codediff.nvim)
-- [render-markdown.nvim](https://github.com/meanderingprogrammer/render-markdown.nvim)
-- [git-conflict.nvim](https://github.com/akinsho/git-conflict.nvim)
-- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)
-- [nvim-cmp](https://github.com/hrsh7th/nvim-cmp)
-- [blink.cmp](https://github.com/saghen/blink.cmp)
-- [blink.pairs](https://github.com/saghen/blink.pairs)
-- [vim-which-key](https://github.com/liuchengxu/vim-which-key)
-- [which-key.nvim](https://github.com/folke/which-key.nvim)
-- [todo-comments.nvim](https://github.com/folke/todo-comments.nvim)
-- [trouble.nvim](https://github.com/folke/trouble.nvim)
-- [nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua)
-- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
-- [telescope-file-browser.nvim](https://github.com/nvim-telescope/telescope-file-browser.nvim)
-- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
-- [lsp-config](https://github.com/neovim/lsp-config)
-- [lspsaga.nvim](https://github.com/glepnir/lspsaga.nvim)
-- [leap.nvim](https://github.com/ggandor/leap.nvim)
-- [flash.nvim](https://github.com/folke/flash.nvim)
-- [snacks.nvim](https://github.com/folke/snacks.nvim)
-- [neotest](https://github.com/nvim-neotest/neotest)
-- [rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim)
-- [copilot.vim](https://github.com/github/copilot.vim)
-- [copilot.lua](https://github.com/zbirenbaum/copilot.lua)
-- [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo)
-- [virt-column.nvim](https://github.com/lukas-reineke/virt-column.nvim)
-- [conflict.nvim](https://github.com/is0n/conflict.nvim)
-
-### Plugin showcase
+## Requirements
 
-You can see a lot of screenshots of themed plugins in the [wiki page](https://github.com/uloco/bluloco.nvim/wiki#screenshots).
-No config needed, works out of the box.
+[lush.nvim](https://github.com/rktjmp/lush.nvim) is required.
 
-## Install
+## Installation
 
 Install Bluloco with your favorite package manager.
 
@@ -99,9 +62,6 @@ vim.pack.add({
     'https://github.com/uloco/bluloco.nvim',
     'https://github.com/rktjmp/lush.nvim',
 })
-
--- If configuring the colorscheme is wanted
-require('bluloco').setup({})
 ```
 
 ### [lazy.nvim](https://github.com/folke/lazy.nvim)
@@ -113,26 +73,15 @@ require('bluloco').setup({})
   priority = 1000,
   dependencies = { 'rktjmp/lush.nvim' },
   opts = {},
-},
+}
 ```
 
 ## Usage
 
-> ⚠️ The `setup()` function is optional but please call it
-> **before** you set the colorscheme if you want to adjust the config.
-
-These are the default values:
+> Note: The `setup()` function is optional. Call it before you set the colorscheme
+> if you want to adjust the configuration.
 
 ```lua
-require("bluloco").setup({
-  style = "auto",               -- "auto" | "dark" | "light"
-  transparent = false,
-  italics = false,
-  terminal = vim.fn.has("gui_running") == 1, -- bluoco colors are enabled in gui terminals per default.
-  guicursor = true,
-  float_window = "default" -- "default" | "transparent"
-})
-
 vim.opt.termguicolors = true
 vim.cmd('colorscheme bluloco')
 ```
@@ -145,72 +94,144 @@ These are especially helpful when switching in an already running vim session.
 :colorscheme bluloco-light
 ```
 
-#### Lualine
+## Configuration
 
-Make sure your lualine settings are set to auto:
+These are the default values:
 
 ```lua
-require('lualine').setup({
-  options = {
-    theme = 'auto'
-  }
+require("bluloco").setup({
+  style = "auto", -- "auto" | "dark" | "light"
+  transparent = false,
+  italics = false,
+  terminal = vim.fn.has("gui_running") == 1, -- bluloco colors are enabled in gui terminals per default.
+  guicursor = true,
+  float_window = "default" -- "default" | "transparent"
 })
 ```
 
-## Config
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `style` | `"auto"` \| `"dark"` \| `"light"` | `"auto"` | Select the variant. `"auto"` follows `vim.o.background`. |
+| `transparent` | `boolean` | `false` | Use the terminal background. |
+| `italics` | `boolean` | `false` | Use italics for keywords, comments, and markup attributes. |
+| `terminal` | `boolean` | GUI: `true`; terminal: `false` | Set builtin terminal colors. |
+| `guicursor` | `boolean` | `true` | Set a colored `guicursor`. |
+| `float_window` | `"default"` \| `"transparent"` | `"default"` | Control float backgrounds with transparency. |
 
 ### style
 
 There are three styles you can configure here: `auto`, `dark` and `light`.
 The `auto` setting is the default and will adjust automatically to your
 `vim.o.background` value. If you change this value during runtime, it will also adjust accordingly.
 
-> ℹ️ The style value only applies if you set the theme with `vim.cmd('colorscheme bluloco')`.
-> Setting the theme with a variant directly will override this setting.
+> Note: The style value only applies if you set the theme with
+> `vim.cmd('colorscheme bluloco')`. Setting a variant directly overrides it.
 
-### transparency (default: false)
+### transparent
 
-This setting will disable the background and use the default background of your terminal.
-You need to enable this if you want the terminal to be transparent. You would still need to
+Disables the background and uses the default background of your terminal.
+Enable it if you want the terminal to be transparent. You still need to
 configure your terminal accordingly for light and dark backgrounds when switching often.
 
-### italics (default: false)
+### italics
 
-This setting will enable italics for _keywords_, _comments_ and _markup attributes_.
+Enables italics for _keywords_, _comments_ and _markup attributes_.
 
-### terminal (default: true in gui, otherwise false)
+### terminal
 
-This setting will enable the bluloco colors in your integrated terminal.
+Enables the bluloco colors in your integrated terminal.
 You most likely want to keep your terminal colors instead of overriding them if you are running neovim in a terminal.
 When you are running neovim inside a gui application this setting is enabled per default.
 
 You can skip the `terminal` setting completely to have it disabled in terminals and enabled in gui neovim.
 
-> ℹ️ Please note that some terminals will display bold text as the bright color variant but enabling this feature will override this behavior in the integrated terminal. This is by design and has nothing to do with this theme. [see](https://github.com/neovim/neovim/issues/11335)
+> Note: Some terminals display bold text with the bright color variant. This
+> option overrides that behavior in the integrated terminal. This behavior is not
+> related to this theme. [See the Neovim issue](https://github.com/neovim/neovim/issues/11335).
 
-### guicursor (default: true)
+### guicursor
 
-This setting sets a guicursor to fix your terminal cursor and make it colorful (as intended).
+Sets a guicursor to fix your terminal cursor and make it colorful (as intended).
 It is enabled by default.
 If you want to override this, make sure to set your `:set guicursor` after loading the theme or disable it completely.
 
-### float_window (default: "default")
+### float_window
 
 Controls how floating windows look when `transparent` is enabled.
 The default keeps a solid float background for better contrast, while setting it to `"transparent"` will also make floating windows inherit your terminal background (useful if you prefer a fully transparent UI).
 
-<!-- ## Recipes
-### Auto switching light & dark themes
- -->
+## Plugin support
 
-## Terminal Colors
+Currently supported (aka. tested) plugins:
 
-I've added a bunch of terminal themes for your terminal emulators. I've used the great [iTerm-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes)
-repository for this, thanks @mbadolato!
+- [treesitter](https://github.com/nvim-treesitter/nvim-treesitter)
+- [hlargs](https://github.com/m-demare/hlargs.nvim)
+- [alpha-nvim](https://github.com/goolord/alpha-nvim)
+- [nvim-notify](https://github.com/rcarriga/nvim-notify)
+- [mason.nvim](https://github.com/williamboman/mason.nvim)
+- [nvim-cursorword](https://github.com/xiyaowong/nvim-cursorword)
+- [vim-illuminate](https://github.com/RRethy/vim-illuminate)
+- [nvim-scrollbar](https://github.com/petertriho/nvim-scrollbar)
+- [lualine.nvim](https://github.com/hoob3rt/lualine.nvim)
+- [barbar.nvim](https://github.com/romgrk/barbar.nvim)
+- [nvim-bufferline.lua](https://github.com/akinsho/nvim-bufferline.lua)
+- [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim)
+- [neogit](https://github.com/TimUntersberger/neogit)
+- [diffview.nvim](https://github.com/sindrets/diffview.nvim)
+- [codediff.nvim](https://github.com/esmuellert/codediff.nvim)
+- [render-markdown.nvim](https://github.com/meanderingprogrammer/render-markdown.nvim)
+- [git-conflict.nvim](https://github.com/akinsho/git-conflict.nvim)
+- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)
+- [vim-fugitive](https://github.com/tpope/vim-fugitive)
+- [nvim-cmp](https://github.com/hrsh7th/nvim-cmp)
+- [blink.cmp](https://github.com/saghen/blink.cmp)
+- [blink.pairs](https://github.com/saghen/blink.pairs)
+- [minuet-ai.nvim](https://github.com/milanglacier/minuet-ai.nvim)
+- [vim-which-key](https://github.com/liuchengxu/vim-which-key)
+- [which-key.nvim](https://github.com/folke/which-key.nvim)
+- [todo-comments.nvim](https://github.com/folke/todo-comments.nvim)
+- [trouble.nvim](https://github.com/folke/trouble.nvim)
+- [nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua)
+- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
+- [telescope-file-browser.nvim](https://github.com/nvim-telescope/telescope-file-browser.nvim)
+- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
+- [lsp-config](https://github.com/neovim/lsp-config)
+- [lspsaga.nvim](https://github.com/glepnir/lspsaga.nvim)
+- [leap.nvim](https://github.com/ggandor/leap.nvim)
+- [flash.nvim](https://github.com/folke/flash.nvim)
+- [snacks.nvim](https://github.com/folke/snacks.nvim)
+- [neotest](https://github.com/nvim-neotest/neotest)
+- [rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim)
+- [copilot.vim](https://github.com/github/copilot.vim)
+- [copilot.lua](https://github.com/zbirenbaum/copilot.lua)
+- [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo)
+- [virt-column.nvim](https://github.com/lukas-reineke/virt-column.nvim)
+- [conflict.nvim](https://github.com/is0n/conflict.nvim)
 
-They are located at `terminal-themes/`. Please follow your terminals installation guide in how to apply them.
+<!-- panvimdoc-ignore-start -->
+
+### Plugin showcase
+
+You can see a lot of screenshots of themed plugins in the [wiki page](https://github.com/uloco/bluloco.nvim/wiki#screenshots).
+No config needed, works out of the box.
+
+<!-- panvimdoc-ignore-end -->
+
+## Integrations
 
-## Switching light and dark theme according your OS settings
+### Lualine
+
+Make sure your lualine settings are set to auto:
+
+```lua
+require('lualine').setup({
+  options = {
+    theme = 'auto'
+  }
+})
+```
+
+### Switching light and dark with your OS
 
 This themes light and dark variant are meant to be used during day and night.
 To make this easily possible I am using the [auto-dark-mode.nvim](https://github.com/f-person/auto-dark-mode.nvim) plugin
@@ -242,6 +263,13 @@ auto_dark_mode.setup({
 If you are also using lazygit as your git client, you might be interested in this [wiki guide](https://github.com/uloco/bluloco.nvim/wiki/Lazygit-%E2%80%90-Delta-%E2%80%90-Bat-%E2%80%90-Auto-Style) to set it up correctly with bluloco.
 Auto-dark light mode included.
 
+### Terminal colors
+
+I've added a bunch of terminal themes for your terminal emulators. I've used the great [iTerm-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes)
+repository for this, thanks @mbadolato!
+
+They are located at `terminal-themes/`. Please follow your terminals installation guide in how to apply them.
+
 ## Contributing
 
 I'd be more than happy for any bugs you find and add an [issue](https://github.com/uloco/bluloco.nvim/issues).