nvim-plugins/telescope.nvim
1
0
Fork 0
mirror of https://github.com/nvim-telescope/telescope.nvim synced 2024-09-16 21:24:02 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat: Add vim docs & generators (#370)

Browse source 
* 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 2021-02-24 21:44:51 -05:00 committed by GitHub
parent 8b3d08d7a6
commit 55ab5c77a5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 558 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
.github/workflows/docgen.yml vendored Normal file
View file

@ -0,0 +1,70 @@
name: Generate docs
on: push
jobs:
build-sources:
name: Generate docs
runs-on: ubuntu-20.04
if: github.ref != 'master'
steps:
- uses: actions/checkout@v2
- run: date +%F > todays-date
- name: Restore cache for today's nightly.
uses: actions/cache@v2
with:
path: build
key: ${{ runner.os }}-appimage-${{ hashFiles('todays-date') }}
- name: Restore cache for tree-sitter
uses: actions/cache@v2
with:
path: _ts
key: ${{ runner.os }}-ts-${{ hashFiles('todays-date') }}
- name: Prepare
run: |
test -d build || {
mkdir -p build
wget https://github.com/neovim/neovim/releases/download/nightly/nvim.appimage
chmod +x nvim.appimage
mv nvim.appimage ./build/nvim
}
test -d _ts || {
# Pining version. Not sure if we should actually do that
mkdir -p _ts
wget https://github.com/tree-sitter/tree-sitter/releases/download/0.17.3/tree-sitter-linux-x64.gz
gzip -d tree-sitter-linux-x64
chmod +x tree-sitter-linux-x64
mv tree-sitter-linux-x64 ./_ts/tree-sitter
}
mkdir -p ~/.local/share/nvim/site/pack/vendor/start
git clone --depth 1 https://github.com/tjdevries/tree-sitter-lua ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start
- name: Build parser
run: |
# We have to build the parser every single time to keep up with parser changes
export PATH="${PWD}/_ts/:${PATH}"
cd ~/.local/share/nvim/site/pack/vendor/start/tree-sitter-lua
mkdir -p build parser
make build_parser
ln -s ../build/parser.so parser/lua.so
cd
# inspired by nvim-lspconfigs
- name: Generating docs
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COMMIT_MSG: |
[Actions] Generate Documentation
skip-checks: true
run: |
export PATH="${PWD}/build/:${PATH}"
git config user.email "actions@github"
git config user.name "Github Actions"
git remote set-url origin https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
make docgen
git add doc/
# Only commit and push if we have changes
git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push origin HEAD:${GITHUB_REF})

1
.gitignore vendored
View file

@ -1 +1,2 @@
build/
doc/tags

48
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,48 @@
# Documentation
is generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation will be exported that is part of the returning module. So example:
local m = {}
--- Test Header
--@return 1: Returns always 1
function m.a()
return 1
end
return m
Something like this.
What is missing?
The docgen has some problems on which people can work. This would happen in https://github.com/tjdevries/tree-sitter-lua and documentation of some modules here.
I would suggest we are documenting lua/telescope/builtin/init.lua rather than the files itself. We can use that init.lua file as "header" file, so we are not cluttering the other files.
How to do it:
## Auto-updates from CI
The easy way would be after this PR is merged
write some docs
commit and push
wait a minute until the CI generates a new commit with the changes
Look at this commit and the changes
And apply new changes with git commit --amend and git push --force to remove that github ci commit again.
Repeat until done
## Generate on your local machine
The other option would be setting up https://github.com/tjdevries/tree-sitter-lua
Install Treesitter, either with package manager or with github release
Install plugin as usual
cd to plugin
mkdir -p build parser Sadly does doesn't exist laughing
make build_parser
ln -s ../build/parser.so parser/lua.so We need the so in parser/ so it gets picked up by neovim. Either copy or symbolic link
Make sure that nvim-treesitter lua parser is not installed and also delete the lua queries in that repository. queries/lua/*. If you are not doing that you will have a bad time
cd into this project
Write doc
Run make docgen
Repeat last two steps

3
Makefile
View file

@ -3,3 +3,6 @@ test:
lint:
luacheck lua/telescope
docgen:
nvim --headless --noplugin -u scripts/minimal_init.vim -c "luafile ./scripts/gendocs.lua" -c 'qa'

32
doc/secret.txt Normal file
View file

@ -0,0 +1,32 @@
================================================================================
*telescope.theprimeagen*
To The Viewers: ~
Oh why hello, I didn't see you there. So nice of you to join us. The Primeagen
must have sent you here.
The places you want to look for help are: (you can do `:help <name>` below)
- |telescope.nvim|
- |telescope.setup|
- |telescope.builtin|
- |telescope.layout|
- |telescope.actions|
I hope you enjoy telescope & Neovim. May your programming always be fun and
your vimming be quick.
To The Primeagen: ~
Cyrnfr ernq guvf uryc znahny orsber pnyyvat zr ng 3 NZ jvgu gryrfpbcr
rzretrapvrf. V xabj ynfg gvzr jr fnirq gur ragver fgernzvat vaqhfgel, ohg
V unir n lbhat fba jub xrrcf zr hc ng avtug nyy ol uvzfrys. OGJ, unir lbh
pbafvqrerq fraqvat culfvpny QIQf sbe znkvzhz dhnyvgl naq rneyl npprff gb arj
pbagrag? Vg frrzf yvxr vg pbhyq or n cerggl pbby vqrn.
#FunzryrffFrysCebzbgvba: uggcf://tvguho.pbz/fcbafbef/gwqrievrf
vim:tw=78:ts=8:ft=help:norl:

197
doc/telescope.txt Normal file
View file

@ -0,0 +1,197 @@
================================================================================
*telescope.nvim*
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
telescope.extensions() *telescope.extensions()*
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.load_extension({name}) *telescope.load_extension()*
Load an extension.
Parameters: ~
{name} (string) Name of the extension
telescope.register_extension({mod}) *telescope.register_extension()*
Register an extension. To be used by plugin authors.
Parameters: ~
{mod} (table) Module
telescope.setup({opts}) *telescope.setup()*
Setup function to be run by user. Configures the defaults, extensions
and other aspects of telescope.
Valid keys for {opts.defaults}
*telescope.defaults.scroll_strategy*
scroll_strategy: ~
Determines what happens you try to scroll past view of the picker.
Available options are:
- "cycle" (default)
- "limit"
*telescope.defaults.selection_strategy*
selection_strategy: ~
Determines how the cursor acts after each sort iteration.
Available options are:
- "reset" (default)
- "follow"
- "row"
*telescope.defaults.sorting_strategy*
sorting_strategy: ~
Determines the direction "better" results are sorted towards.
Available options are:
- "descending" (default)
- "ascending"
Parameters: ~
{opts} (table) Configuration opts. Keys: defaults, extensions
================================================================================
*telescope.builtin*
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
builtin.live_grep() *builtin.live_grep()*
Live grep means grep as you type.
================================================================================
*telescope.layout*
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|
layout_strategies.center() *layout_strategies.center()*
Centered layout wih smaller default sizes (I think)
+--------------+
| Preview |
+--------------+
| Prompt |
+--------------+
| Result |
| Result |
| Result |
+--------------+
layout_strategies.flex() *layout_strategies.flex()*
Swap between `horizontal` and `vertical` strategies based on the window
width
- Supports `vertical` or `horizontal` features
Uses:
flip_columns
flip_lines
layout_strategies.horizontal() *layout_strategies.horizontal()*
Horizontal previewer
+-------------+--------------+
| | |
| Results | |
| | Preview |
| | |
+-------------| |
| Prompt | |
+-------------+--------------+
layout_strategies.vertical() *layout_strategies.vertical()*
Vertical perviewer stacks the items on top of each other.
+-----------------+
| Previewer |
| Previewer |
| Previewer |
+-----------------+
| Result |
| Result |
| Result |
+-----------------+
| Prompt |
+-----------------+
vim:tw=78:ts=8:ft=help:norl:

26
lua/telescope/builtin/init.lua
View file

@ -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

36
lua/telescope/config.lua
View file

@ -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", {})

48
lua/telescope/init.lua
View file

@ -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

140
lua/telescope/pickers/layout_strategies.lua
View file

@ -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 {}

34
scripts/gendocs.lua Normal file
View file

@ -0,0 +1,34 @@
-- Setup telescope with defaults
require('telescope').setup()
local docgen = require('docgen')
local docs = {}
docs.test = function()
-- TODO: Fix the other files so that we can add them here.
local input_files = {
"./lua/telescope/init.lua",
"./lua/telescope/builtin/init.lua",
"./lua/telescope/pickers/layout_strategies.lua",
}
table.sort(input_files, function(a, b)
return #a < #b
end)
local output_file = "./doc/telescope.txt"
local output_file_handle = io.open(output_file, "w")
for _, input_file in ipairs(input_files) do
docgen.write(input_file, output_file_handle)
end
output_file_handle:write(" vim:tw=78:ts=8:ft=help:norl:\n")
output_file_handle:close()
vim.cmd [[checktime]]
end
docs.test()
return docs

1
scripts/minimal_init.vim
View file

@ -1,6 +1,7 @@
set rtp+=.
set rtp+=../plenary.nvim/
set rtp+=../popup.nvim/
set rtp+=../tree-sitter-lua/
runtime! plugin/plenary.vim
runtime! plugin/telescope.vim