doc!: reorganize all documentation (fix #144)

Documentation is now produced generated from three sources:

-       The README.md, automatically using panvimdoc
-       The Lua code (Emmy docs), automatically using lemmy-help
-       The options, manually (for now)

.github/workflows/docs.yaml

@@ -0,0 +1,39 @@
+name: Generate docs
+
+on:
+  push:
+    branches:
+    - main
+    - gen-docs
+    paths:
+    - '.github/**'
+    - 'doc/**'
+    - 'lua/**'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: Generate Fidget documentation
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: API docs from code
+      run: |
+        curl -Lq https://github.com/numToStr/lemmy-help/releases/latest/download/lemmy-help-x86_64-unknown-linux-gnu.tar.gz | tar xz
+        ./lemmy-help -f -a -c -t lua/{fidget.lua,fidget/notification.lua,fidget/progress.lua,fidget/progress/lsp.lua,fidget/spinner.lua} > doc/fidget-api.txt
+
+    - name: Usage docs from README (panvimdoc)
+      uses: kdheepak/panvimdoc@main
+      with:
+        pandoc: README.md
+        vimdoc: fidget
+        description: Extensible UI for Neovim notifications and LSP progress messages.
+        version: "NVIM v0.8.0"
+        demojify: true
+        treesitter: true
+        shiftheadinglevelby: -1
+
+    - uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: "Auto generate docs"
+        branch: ${{ github.head_ref }}

.gitignore

@@ -1 +1,2 @@
+/.luarc.json
 /doc/tags

README.md

@@ -1,4 +1,6 @@
-# fidget.nvim
+<!-- panvimdoc-ignore-start -->
+
+# 😵 Fidget
 
 Extensible UI for Neovim notifications and LSP progress messages.
 
@@ -65,7 +67,9 @@ who doesn't love a little bit of terminal eye candy, as a treat?
 [lsp-progress]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#progress
 [vim-notify]: https://neovim.io/doc/user/lua.html#vim.notify()
 
-## Quickstart
+<!-- panvimdoc-ignore-end -->
+
+## Getting Started
 
 ### Requirements
 
@@ -76,7 +80,6 @@ with an LSP server that uses the [`$/progress`][lsp-progress] handler.
 For an up-to-date list of LSP servers this plugin is known to work with, see
 [this Wiki page](https://github.com/j-hui/fidget.nvim/wiki/Known-compatible-LSP-servers).
 
-
 ### Installation
 
 Install this plugin using your favorite plugin manager.
@@ -98,19 +101,133 @@ See the [documentation](doc/fidget.md) for `setup()` options.
 
 ```vim
 Plug 'j-hui/fidget.nvim'
-```
 
-Make sure the plugin is installed run `:PlugInstall`.
+" Make sure the plugin is installed using :PlugInstall. Then, somewhere after plug#end():
+lua <<EOF
+require("fidget").setup {
+  -- options
+}
+EOF
+```
 
-After the plugin is loaded (e.g., after `plug#end()` for vim-plug), call its
-`setup` function (in Lua):
+## Options
 
 ```lua
-require("fidget").setup {
-  -- options
+{
+  -- Options related to LSP progress subsystem
+  progress = {
+    poll_rate = 0,                -- How and when to poll for progress messages
+    suppress_on_insert = false,   -- Suppress new messages while in insert mode
+    ignore_done_already = false,  -- Ignore new tasks that are already complete
+    ignore_empty_message = false, -- Ignore new tasks that don't contain a message
+    clear_on_detach =             -- Clear notification group when LSP server detaches
+      function(client_id)
+        local client = vim.lsp.get_client_by_id(client_id)
+        return client and client.name or nil
+      end,
+    notification_group =          -- How to get a progress message's notification group key
+      function(msg) return msg.lsp_client.name end,
+    ignore = {},                  -- List of LSP servers to ignore
+
+    -- Options related to how LSP progress messages are displayed as notifications
+    display = {
+      render_limit = 16,          -- How many LSP messages to show at once
+      done_ttl = 3,               -- How long a message should persist after completion
+      done_icon = "✔",            -- Icon shown when all LSP progress tasks are complete
+      done_style = "Constant",    -- Highlight group for completed LSP tasks
+      progress_ttl = math.huge,   -- How long a message should persist when in progress
+      progress_icon =             -- Icon shown when LSP progress tasks are in progress
+        { pattern = "dots", period = 1 },
+      progress_style =            -- Highlight group for in-progress LSP tasks
+        "WarningMsg",
+      group_style = "Title",      -- Highlight group for group name (LSP server name)
+      icon_style = "Question",    -- Highlight group for group icons
+      priority = 30,              -- Ordering priority for LSP notification group
+      format_message =            -- How to format a progress message
+        require("fidget.progress.display").default_format_message,
+      format_annote =             -- How to format a progress annotation
+        function(msg) return msg.title end,
+      format_group_name =         -- How to format a progress notification group's name
+        function(group) return tostring(group) end,
+      overrides = {               -- Override options from the default notification config
+        rust_analyzer = { name = "rust-analyzer" },
+      },
+    },
+
+    -- Options related to Neovim's built-in LSP client
+    lsp = {
+      progress_ringbuf_size = 0,  -- Configure the nvim's LSP progress ring buffer size
+    },
+  },
+
+  -- Options related to notification subsystem
+  notification = {
+    poll_rate = 10,               -- How frequently to update and render notifications
+    filter = vim.log.levels.INFO, -- Minimum notifications level
+    override_vim_notify = false,  -- Automatically override vim.notify() with Fidget
+    configs =                     -- How to configure notification groups when instantiated
+      { default = require("fidget.notification").default_config },
+
+    -- Options related to how notifications are rendered as text
+    view = {
+      stack_upwards = true,       -- Display notification items from bottom to top
+      icon_separator = " ",       -- Separator between group name and icon
+      group_separator = "---",    -- Separator between notification groups
+      group_separator_hl =        -- Highlight group used for group separator
+        "Comment",
+    },
+
+    -- Options related to the notification window and buffer
+    window = {
+      normal_hl = "Comment",      -- Base highlight group in the notification window
+      winblend = 100,             -- Background color opacity in the notification window
+      border = "none",            -- Border around the notification window
+      zindex = 45,                -- Stacking priority of the notification window
+      max_width = 0,              -- Maximum width of the notification window
+      max_height = 0,             -- Maximum height of the notification window
+      x_padding = 1,              -- Padding from right edge of window boundary
+      y_padding = 0,              -- Padding from bottom edge of window boundary
+      align = "bottom",           -- How to align the notification window
+      relative = "editor",        -- What the notification window position is relative to
+    },
+  },
+
+  -- Options related to logging
+  logger = {
+    level = vim.log.levels.WARN,  -- Minimum logging level
+    float_precision = 0.01,       -- Limit the number of decimals displayed for floats
+    path =                        -- Where Fidget writes its logs to
+      string.format("%s/fidget.nvim.log", vim.fn.stdpath("cache")),
+  },
 }
 ```
 
+<!-- panvimdoc-ignore-start -->
+
+For more details, see [fidget-option.txt](doc/fidget-option.txt).
+
+<!-- panvimdoc-ignore-end -->
+
+<!-- panvimdoc-include-comment For more details, see |fidget-option.txt|. -->
+
+## Lua API
+
+<!-- panvimdoc-ignore-start -->
+
+Fidget has a Lua API, with [documentation](doc/fidget-api.txt) generated from
+source code. You are encouraged to hack around with that.
+
+<!-- panvimdoc-ignore-end -->
+
+<!-- panvimdoc-include-comment See |fidget-api.txt|. -->
+
+## Highlights
+
+Rather than defining its own highlights, Fidget uses built-in highlight groups
+that are typically overridden by custom Vim color schemes. With any luck, these
+will look reasonable when rendered, but the visual outcome will really depend
+on what your color scheme decided to do with those highlight groups.
+
 ## Related Work
 
 [rcarriga/nvim-notify](https://github.com/rcarriga/nvim-notify) is first and