chore(ci): auto generate docs

doc/mellifluous.txt

@@ -6,9 +6,11 @@ Table of Contents                              *mellifluous-table-of-contents*
 1. Styled plugins                                 |mellifluous-styled-plugins|
 2. Installation and usage                 |mellifluous-installation-and-usage|
 3. Configuration                                   |mellifluous-configuration|
-  - Setting light theme        |mellifluous-configuration-setting-light-theme|
+  - Light theme                        |mellifluous-configuration-light-theme|
   - Color sets                          |mellifluous-configuration-color-sets|
-  - Overriding highlights    |mellifluous-configuration-overriding-highlights|
+  - Color overrides                |mellifluous-configuration-color-overrides|
+  - Highlight overrides        |mellifluous-configuration-highlight-overrides|
+  - Available colors              |mellifluous-configuration-available-colors|
 4. CLI options                                       |mellifluous-cli-options|
 5. TODO                                                     |mellifluous-todo|
 6. Ports                                                   |mellifluous-ports|
@@ -114,10 +116,10 @@ parts of the config can be included.
 <
 
 
-SETTING LIGHT THEME            *mellifluous-configuration-setting-light-theme*
+LIGHT THEME                            *mellifluous-configuration-light-theme*
 
-Set `vim.opt.background` to `'light'`. This will only work on color sets that
-have light theme.
+For light theme, set `vim.opt.background` to `'light'`. This will only work on
+color sets that have light theme.
 
 
 COLOR SETS                              *mellifluous-configuration-color-sets*
@@ -151,101 +153,99 @@ Default config:
 <
 
 
-OVERRIDING COLORS OF A COLOR SET ~
+COLOR OVERRIDES                    *mellifluous-configuration-color-overrides*
 
 The following snippet shows where and which colors can be overridden:
 
 >lua
     require 'mellifluous'.setup({
         <color_set_name> = { -- name any of the defined color sets
             color_overrides = {
-                dark = { -- dark variant of the color set
-                    bg = nil, -- used for shades, on some color sets fg will be derived from this
-                    fg = nil, -- used for shades if shades_fg is undefined
-                    shades_fg = nil, -- used for shades (dimmed foregrounds)
-
-                    main_keywords = nil,
-                    other_keywords = nil,
-                    types = nil,
-                    operators = nil,
-                    strings = nil,
-                    functions = nil,
-                    constants = nil,
-                    comments = nil,
-
-                    red = nil, -- errors, deletes, bad spellings
-                    orange = nil, -- warnings, changes, unusual spellings
-                    green = nil, -- staged, additions
-                    blue = nil, -- information, new files
-                    purple = nil, -- hints, merge
-
-                    -- for better terminal highlights
-                    yellow = nil,
-                    cyan = nil,
+                dark = { -- for dark theme
+                    bg = nil, -- used for bg shades and may be used for some colorset colors
+                    colors = function(colors)
+                        return {
+                            -- return overridden colors here
+                            -- check available colors section for colors that can be used and overriden.
+                        }
+                    end,
                 },
-                light = { -- light variant of the color set
+                light = { -- for light theme
                     -- same keys as in dark variant
                 },
             }
         }
     })
 <
 
-For example, to override a color for the main keywords group in the dark
-version of the mellifluous color set, one could do the following:
+To override colors for all colorsets, omit `<color_set_name>` table.
+
+NOTE: parameter `colors` will have all of the colors set by the colorset, but
+it will not have shades.
+
+Example:
 
 >lua
     require 'mellifluous'.setup({
+        -- invert bg shades for all colorsets
+        color_overrides = {
+            dark = {
+                colors = function(colors)
+                    return {
+                        bg2 = colors.bg:darkened(2),
+                        bg3 = colors.bg:darkened(4),
+                        bg4 = colors.bg:darkened(6),
+                        bg5 = colors.bg:darkened(8),
+                    }
+                end,
+            }
+        },
+        -- modify some colors for mellifluous colorset
         mellifluous = {
             color_overrides = {
                 dark = {
-                    main_keywords = '#e0e066'
+                    bg = function(bg)
+                        return bg:lightened(2)
+                    end,
+                    colors = function(colors)
+                        return {
+                            main_keywords = '#e0e066',
+                            operators = colors.functions:desaturated(10),
+                        }
+                    end,
                 }
             }
         }
     })
 <
 
 
-OVERRIDING HIGHLIGHTS OF A COLOR SET ~
-
-The following snippet shows how highlight overrides can be defined for a
-specific color set:
-
->lua
-    require 'mellifluous'.setup({
-        <color_set_name> = { -- name any of the defined color sets
-            -- config structure from here is the same as for global highlight overrides
-        }
-    })
-<
-
-For further instructions, refer to |mellifluous-overriding-highlights| section
-
-
-EXTRA COLORS
+HIGHLIGHT OVERRIDES            *mellifluous-configuration-highlight-overrides*
 
-In addition to the colors listed in |mellifluous-available-colors| section,
-some color sets may have more colors available (`cyan`). To check your color
-set, refer to the source code for color sets <lua/mellifluous/colors/sets/> and
-see if `get_colors_*` functions return any extra (optional) colors.
-
-
-OVERRIDING HIGHLIGHTS        *mellifluous-configuration-overriding-highlights*
-
-The following snippet shows how global (for any color set) highlight overrides
-can be defined:
+The following snippet shows how highlight overrides can be defined:
 
 >lua
     require 'mellifluous'.setup({
+        -- highlight overrides for all colorsets
         highlight_overrides = {
-            dark = function(highlighter, colors) -- dark variant of the color set
+            dark = function(highlighter, colors) -- dark theme
                 -- set highlights here (using highlighter)
             end,
-            light = function(highlighter, colors) -- light variant of the color set
+            light = function(highlighter, colors) -- light theme
                 -- set highlights here (using highlighter)
             end,
         }
+        -- highlight overrides for specific colorset
+        <colorset_name> = {
+            highlight_overrides = {
+                dark = function(highlighter, colors) -- dark variant of the color set
+                    -- set highlights here (using highlighter)
+                end,
+                light = function(highlighter, colors) -- light variant of the color set
+                    -- set highlights here (using highlighter)
+                end,
+            }
+        }
     })
 <
 
@@ -278,41 +278,37 @@ This function returns highlight definition map for highlight group with the
 requested name.
 
 
-AVAILABLE COLORS ~
-
-To use one of the available colors from a color set, in highlight definition
-map, set the value of `fg`, `bg` or `sp` key to `colors.available_color`
-
-Available colors:
-
-- Syntax element colors.
-    - `main_keywords`: used to indicate keywords related to control flow.
-    - `other_keywords`
-    - `types`
-    - `operators`
-    - `strings`
-    - `functions`
-    - `constants`
-    - `comments`
-    - `fg`: in code – identifiers.
-    - `bg`
-- Named colors. Used for terminal colors, but most of these colors will match some syntax element color.
-    - `red`
-    - `orange`
-    - `green`
-    - `blue`
-    - `purple`
-    - `yellow`
-- UI colors. Same as named colors, but all are of the same brightness (lightness).
-    - `ui_red`: used to indicate errors, deletes, bad spellings.
-    - `ui_orange`: used to indicate warnings, changes, other (strange) spellings.
-    - `ui_green`: used to indicate staged, additions.
-    - `ui_blue`: used to indicate information, new files.
-    - `ui_purple`: used to indicate hints, merge.
-    - `ui_yellow`
-
-NOTE: some color sets may have more colors available. See
-|mellifluous-extra-colors| section.
+AVAILABLE COLORS                  *mellifluous-configuration-available-colors*
+
+Named colors are used several times in configuration (as parameter `colors` of
+some function). This section lists and explains those colors.
+
+Available colors: - Syntax element colors - `main_keywords`: used to indicate
+keywords related to control flow. - `other_keywords` - `types` - `operators` -
+`strings` - `functions` - `constants` - `comments` - `fg`: in code –
+identifiers. - `bg` - Named colors: used for terminal colors, but most of these
+colors will match some syntax element color. - `red` - `orange` - `green` -
+`blue` - `purple` - `yellow` - Shades: colors that are derived from colors
+defined in the colorset (those listed above). - UI colors: same as named
+colors, but all are of the same brightness (lightness). - `ui_red`: used to
+indicate errors, deletes, bad spellings. - `ui_orange`: used to indicate
+warnings, changes, other (strange) spellings. - `ui_green`: used to indicate
+staged, additions. - `ui_blue`: used to indicate information, new files. -
+`ui_purple`: used to indicate hints, merge. - `ui_yellow` - Shades of fg and bg
+colors. These colors might be used for more than explained below. - `fg2`: used
+for statusline, normal text in plugins that open in split windows. - `fg3`:
+used for folded text. - `fg4`: used for line numbers. - `fg5`: used for active
+indent line, "hidden" text. - `dark_bg`: used for background in plugins that
+open in split windows. - `bg2`: used for cursorline/column, some floating
+windows. - `bg3`: used for folded text background, floating windows, showing
+LSP references. - `bg4`: used for visual mode, completion menu, statusline, fg
+of inactive indent line. - `bg5` (only for dark background): indicates a more
+prominent selection than visual, might be deprecated in the future. -
+`dark_bg2`(only for light background): used as a replacement for bg5 and also
+for visual mode
+
+Some colorsets may have more colors available. To check that, refer to the
+source of the colorset <lua/mellifluous/colors/colorsets/>.
 
 
 COLOR FUNCTIONS ~