feat: Add vim docs & generators (#370)
* feat: Add vim docs & generators * example of what we could start to do * Docgen CI job * wip * incremental updates. soon good validation * [Actions] Generate Documentation skip-checks: true * pretty cool now * [Actions] Generate Documentation skip-checks: true * make sure telescope is loaded first * Add updates. Maybe this will not delete now? * Add defaults tags as well * 😄 Co-authored-by: Simon Hauser <Simon-Hauser@outlook.de> Co-authored-by: Github Actions <actions@github>
This commit is contained in:
TJ DeVries
@@ -1,15 +1,17 @@
|
||||
--[[
|
||||
A collection of builtin pipelines for telesceope.
|
||||
---@tag telescope.builtin
|
||||
|
||||
Meant for both example and for easy startup.
|
||||
|
||||
Any of these functions can just be called directly by doing:
|
||||
|
||||
:lua require('telescope.builtin').__name__()
|
||||
|
||||
This will use the default configuration options.
|
||||
Other configuration options still in flux at the moment
|
||||
--]]
|
||||
---@brief [[
|
||||
--- A collection of builtin pickers for telesceope.
|
||||
---
|
||||
--- Meant for both example and for easy startup.
|
||||
---
|
||||
--- Any of these functions can just be called directly by doing:
|
||||
---
|
||||
--- :lua require('telescope.builtin').$NAME()
|
||||
---
|
||||
--- This will use the default configuration options.
|
||||
--- Other configuration options are still in flux at the moment
|
||||
---@brief ]]
|
||||
|
||||
if 1 ~= vim.fn.has('nvim-0.5') then
|
||||
vim.api.nvim_err_writeln("This plugins requires neovim 0.5")
|
||||
@@ -19,7 +21,9 @@ end
|
||||
|
||||
local builtin = {}
|
||||
|
||||
--- Live grep means grep as you type.
|
||||
builtin.live_grep = require('telescope.builtin.files').live_grep
|
||||
|
||||
builtin.grep_string = require('telescope.builtin.files').grep_string
|
||||
builtin.find_files = require('telescope.builtin.files').find_files
|
||||
builtin.fd = builtin.find_files
|
||||
|
||||
@@ -20,6 +20,7 @@ local sorters = require('telescope.sorters')
|
||||
local config = {}
|
||||
|
||||
config.values = _TelescopeConfigurationValues
|
||||
config.descriptions = {}
|
||||
|
||||
function config.set_defaults(defaults)
|
||||
defaults = defaults or {}
|
||||
@@ -28,13 +29,40 @@ function config.set_defaults(defaults)
|
||||
return first_non_null(defaults[name], config.values[name], default_val)
|
||||
end
|
||||
|
||||
local function set(name, default_val)
|
||||
local function set(name, default_val, description)
|
||||
-- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
|
||||
-- assert(description, "Config values must always have a description")
|
||||
|
||||
config.values[name] = get(name, default_val)
|
||||
if description then
|
||||
config.descriptions[name] = vim.trim(description)
|
||||
end
|
||||
end
|
||||
|
||||
set("sorting_strategy", "descending")
|
||||
set("selection_strategy", "reset")
|
||||
set("scroll_strategy", "cycle")
|
||||
set("sorting_strategy", "descending", [[
|
||||
Determines the direction "better" results are sorted towards.
|
||||
|
||||
Available options are:
|
||||
- "descending" (default)
|
||||
- "ascending"
|
||||
]])
|
||||
|
||||
set("selection_strategy", "reset", [[
|
||||
Determines how the cursor acts after each sort iteration.
|
||||
|
||||
Available options are:
|
||||
- "reset" (default)
|
||||
- "follow"
|
||||
- "row"
|
||||
]])
|
||||
|
||||
set("scroll_strategy", "cycle", [[
|
||||
Determines what happens you try to scroll past view of the picker.
|
||||
|
||||
Available options are:
|
||||
- "cycle" (default)
|
||||
- "limit"
|
||||
]])
|
||||
|
||||
set("layout_strategy", "horizontal")
|
||||
set("layout_defaults", {})
|
||||
|
||||
@@ -4,6 +4,30 @@ local _extensions = require('telescope._extensions')
|
||||
|
||||
local telescope = {}
|
||||
|
||||
-- TODO: Add pre to the works
|
||||
-- ---@pre [[
|
||||
-- ---@pre ]]
|
||||
|
||||
---@brief [[
|
||||
--- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
|
||||
--- filter, find and pick things in Lua.
|
||||
---
|
||||
--- To find out more:
|
||||
--- https://github.com/nvim-telescope/telescope.nvim
|
||||
--
|
||||
-- :h telescope.setup
|
||||
-- :h telescope.builtin
|
||||
-- :h telescope.layout
|
||||
-- :h telescope.actions
|
||||
--
|
||||
---@brief ]]
|
||||
|
||||
---@tag telescope.nvim
|
||||
|
||||
--- Setup function to be run by user. Configures the defaults, extensions
|
||||
--- and other aspects of telescope.
|
||||
---@param opts table: Configuration opts. Keys: defaults, extensions
|
||||
---@eval { ["description"] = require('telescope').__format_setup_keys() }
|
||||
function telescope.setup(opts)
|
||||
opts = opts or {}
|
||||
|
||||
@@ -15,15 +39,39 @@ function telescope.setup(opts)
|
||||
_extensions.set_config(opts.extensions)
|
||||
end
|
||||
|
||||
--- Register an extension. To be used by plugin authors.
|
||||
---@param mod table: Module
|
||||
function telescope.register_extension(mod)
|
||||
return _extensions.register(mod)
|
||||
end
|
||||
|
||||
--- Load an extension.
|
||||
---@param name string: Name of the extension
|
||||
function telescope.load_extension(name)
|
||||
return _extensions.load(name)
|
||||
end
|
||||
|
||||
--- Use telescope.extensions to reference any extensions within your configuration.
|
||||
--- While the docs currently generate this as a function, it's actually a table. Sorry.
|
||||
telescope.extensions = require('telescope._extensions').manager
|
||||
|
||||
telescope.__format_setup_keys = function()
|
||||
local descriptions = require('telescope.config').descriptions
|
||||
|
||||
local names = vim.tbl_keys(descriptions)
|
||||
table.sort(names)
|
||||
|
||||
local result = { "", "", "Valid keys for {opts.defaults}" }
|
||||
for _, name in ipairs(names) do
|
||||
local desc = descriptions[name]
|
||||
|
||||
table.insert(result, "")
|
||||
table.insert(result, string.format("%s*telescope.defaults.%s*", string.rep(" ", 70 - 20 - #name), name))
|
||||
table.insert(result, string.format("%s: ~", name))
|
||||
table.insert(result, string.format(" %s", desc))
|
||||
end
|
||||
|
||||
return result
|
||||
end
|
||||
|
||||
return telescope
|
||||
|
||||
@@ -1,28 +1,39 @@
|
||||
--[[
|
||||
---@tag telescope.layout
|
||||
|
||||
Layout strategies are different functions to position telescope.
|
||||
|
||||
horizontal:
|
||||
- Supports `prompt_position`, `preview_cutoff`
|
||||
|
||||
vertical:
|
||||
|
||||
flex: Swap between `horizontal` and `vertical` strategies based on the window width
|
||||
- Supports `vertical` or `horizontal` features
|
||||
|
||||
dropdown:
|
||||
|
||||
|
||||
Layout strategies are callback functions
|
||||
|
||||
-- @param self: Picker
|
||||
-- @param columns: number Columns in the vim window
|
||||
-- @param lines: number Lines in the vim window
|
||||
|
||||
function(self, columns, lines)
|
||||
end
|
||||
|
||||
--]]
|
||||
---@brief [[
|
||||
---
|
||||
--- Layout strategies are different functions to position telescope.
|
||||
---
|
||||
--- All layout strategies are functions with the following signature: >
|
||||
---
|
||||
--- function(picker, columns, lines)
|
||||
--- -- Do some calculations here...
|
||||
--- return {
|
||||
--- preview = preview_configuration
|
||||
--- results = results_configuration,
|
||||
--- prompt = prompt_configuration,
|
||||
--- }
|
||||
--- end
|
||||
--- <
|
||||
---
|
||||
--- Parameters: ~
|
||||
--- - picker : A Picker object. (docs coming soon)
|
||||
--- - columns : number Columns in the vim window
|
||||
--- - lines : number Lines in the vim window
|
||||
---
|
||||
--- TODO: I would like to make these link to `telescope.layout_strategies.*`, but it's not yet possible.
|
||||
---
|
||||
--- Available layout strategies include:
|
||||
--- horizontal:
|
||||
--- - See |layout_strategies.horizontal|
|
||||
---
|
||||
--- vertical:
|
||||
--- - See |layout_strategies.vertical|
|
||||
---
|
||||
--- flex:
|
||||
--- - See |layout_strategies.flex|
|
||||
---
|
||||
---@brief ]]
|
||||
|
||||
local config = require('telescope.config')
|
||||
local resolve = require("telescope.config.resolve")
|
||||
@@ -50,16 +61,16 @@ end
|
||||
|
||||
local layout_strategies = {}
|
||||
|
||||
--[[
|
||||
+-----------------+---------------------+
|
||||
| | |
|
||||
| Results | |
|
||||
| | Preview |
|
||||
| | |
|
||||
+-----------------| |
|
||||
| Prompt | |
|
||||
+-----------------+---------------------+
|
||||
--]]
|
||||
--- Horizontal previewer
|
||||
---
|
||||
--- +-------------+--------------+
|
||||
--- | | |
|
||||
--- | Results | |
|
||||
--- | | Preview |
|
||||
--- | | |
|
||||
--- +-------------| |
|
||||
--- | Prompt | |
|
||||
--- +-------------+--------------+
|
||||
layout_strategies.horizontal = function(self, max_columns, max_lines)
|
||||
local layout_config = validate_layout_config(self.layout_config or {}, {
|
||||
width_padding = "How many cells to pad the width",
|
||||
@@ -144,19 +155,18 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
|
||||
}
|
||||
end
|
||||
|
||||
--[[
|
||||
+--------------+
|
||||
| Preview |
|
||||
+--------------+
|
||||
| Prompt |
|
||||
+--------------+
|
||||
| Result |
|
||||
| Result |
|
||||
| Result |
|
||||
+--------------+
|
||||
|
||||
|
||||
--]]
|
||||
--- Centered layout wih smaller default sizes (I think)
|
||||
---
|
||||
--- +--------------+
|
||||
--- | Preview |
|
||||
--- +--------------+
|
||||
--- | Prompt |
|
||||
--- +--------------+
|
||||
--- | Result |
|
||||
--- | Result |
|
||||
--- | Result |
|
||||
--- +--------------+
|
||||
---
|
||||
layout_strategies.center = function(self, columns, lines)
|
||||
local initial_options = self:_get_initial_window_options()
|
||||
local preview = initial_options.preview
|
||||
@@ -204,19 +214,20 @@ layout_strategies.center = function(self, columns, lines)
|
||||
}
|
||||
end
|
||||
|
||||
--[[
|
||||
+-----------------+
|
||||
| Previewer |
|
||||
| Previewer |
|
||||
| Previewer |
|
||||
+-----------------+
|
||||
| Result |
|
||||
| Result |
|
||||
| Result |
|
||||
+-----------------+
|
||||
| Prompt |
|
||||
+-----------------+
|
||||
--]]
|
||||
--- Vertical perviewer stacks the items on top of each other.
|
||||
---
|
||||
--- +-----------------+
|
||||
--- | Previewer |
|
||||
--- | Previewer |
|
||||
--- | Previewer |
|
||||
--- +-----------------+
|
||||
--- | Result |
|
||||
--- | Result |
|
||||
--- | Result |
|
||||
--- +-----------------+
|
||||
--- | Prompt |
|
||||
--- +-----------------+
|
||||
---
|
||||
layout_strategies.vertical = function(self, max_columns, max_lines)
|
||||
local layout_config = self.layout_config or {}
|
||||
local initial_options = self:_get_initial_window_options()
|
||||
@@ -276,9 +287,12 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
|
||||
}
|
||||
end
|
||||
|
||||
-- Uses:
|
||||
-- flip_columns
|
||||
-- flip_lines
|
||||
--- Swap between `horizontal` and `vertical` strategies based on the window width
|
||||
--- - Supports `vertical` or `horizontal` features
|
||||
---
|
||||
--- Uses:
|
||||
--- flip_columns
|
||||
--- flip_lines
|
||||
layout_strategies.flex = function(self, max_columns, max_lines)
|
||||
local layout_config = self.layout_config or {}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user