feat: Add vim docs & generators

.github/workflows/docgen.yml

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

.gitignore

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

CONTRIBUTING.md

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

Makefile

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

doc/secret.txt

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

doc/telescope.txt

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

lua/telescope/builtin/init.lua

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