chore(docs): prepare :h navigator-nvim

Author: numToStr

.github/workflows/ci.yaml

@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  push:
+    paths:
+      - "**.lua"
+    branches:
+      - master
+
+env:
+  PLUGIN_NAME: Navigator
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    name: emmylua to help doc
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Generating help
+        shell: bash
+        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 -fact lua/Navigator/init.lua lua/Navigator/mux/{vi,tmux,wezterm}.lua > doc/${{env.PLUGIN_NAME}}.txt
+
+      - name: Commit
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          branch: ${{ github.head_ref }}
+          commit_message: "chore(docs): auto-generate `:help` doc"
+          file_pattern: doc/*.txt

README.md

@@ -3,7 +3,7 @@
 
 ![Navigator](https://user-images.githubusercontent.com/24727447/157040356-1f44323a-c7b6-4955-8207-5e6cade08c9e.gif "Navigating to the moon")
 
-This plugin provides a set of [functions](#lua-api) and [commands](#commands) that allows you to seemlessly navigate between neovim and different [terminal multiplexers](#multiplexers).
+`Navigator.nvim` provides set of [functions](#lua-api) and [commands](#commands) that allows you to seemlessly navigate between neovim and different [terminal multiplexers](#multiplexers).
 
 ### 🚀 Installation
 
@@ -54,7 +54,7 @@ vim.keymap.set('n', '<A-p>', '<CMD>NavigatorPrevious<CR>')
 > **Note** - This plugin doesn't provide any configuration for multiplexers, feel free to use (and modify) the snippet for multiplexer of your choice by following the links below.
 
 - [Tmux](https://github.com/numToStr/Navigator.nvim/wiki/Tmux-Integration)
-- [Wezterm](https://github.com/numToStr/Navigator.nvim/wiki/WezTerm-Integration)
+- [WezTerm](https://github.com/numToStr/Navigator.nvim/wiki/WezTerm-Integration)
 
 #### Configuration (optional)
 
@@ -90,6 +90,8 @@ Following options can be given when calling `setup({config})`. Below is the defa
 - `NavigatorDown` - Go to down split/pane
 - `NavigatorPrevious` - Go to previous split/pane
 
+> Read `:h navigator.commands` for more info
+
 #### Lua API
 
 ```lua
@@ -100,6 +102,8 @@ require('Navigator').down()
 require('Navigator').previous()
 ```
 
+> Read `:h navigator.api` for more info
+
 ### 💐 Credits
 
 - [vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) - Motivator and Vimscript cousin

doc/Navigator.txt

@@ -1,32 +1,125 @@
+---@brief [[
+---*navigator-nvim.txt*    For Neovim version 0.7           Last change: 2020 Dec 16
+---
+---
+---                |\ |  _.    o  _   _. _|_  _  ._  ._     o ._ _
+---                | \| (_| \/ | (_| (_|  |_ (_) | o | | \/ | | | |
+---                               _|
+---
+---              · Smoothly navigate between neovim and multipexers ·
+---
+---@brief ]]
+
+---@toc navigator.contents
+
+---@mod navigator-nvim Introduction
+---@brief [[
+---Navigator.nvim provides set of functions and commands that allows you to seemlessly
+---navigate between neovim and different terminal multiplexers. It also allows you to
+---integrate your own custom multipexer.
+---@brief ]]
+
+---@mod navigator.commands Commands
+---@brief [[
+---This plugin provides the following commands:
+---
+--- *NavigatorLeft* - Go to left split/pane
+--- *NavigatorRight* - Go to right split/pane
+--- *NavigatorUp* - Go to upper split/pane
+--- *NavigatorDown* - Go to down split/pane
+--- *NavigatorPrevious* - Go to previous split/pane
+---@brief ]]
+
+---@mod navigator.api API and Config
 local n = require('Navigator.navigate')
+local Nav = {}
 
-local N = {
-    setup = n.setup,
-}
+---@class Config
+---Save modified buffer(s) when moving
+---to mux from neovim (default: `nil`)
+---@field auto_save? '"current"'|'"all"'
+---Disable navigation when the current
+---mux pane is zoomed in (default: `false`)
+---@field disable_on_zoom boolean
+---@field mux '"auto"'|Vi Multiplexer to use (default: "auto")
+
+---Enum of navigation direction analogous of neovim window movement
+---@alias Direction
+---| '"p"' # Previous Pane
+---| '"h"' # Left Pane
+---| '"j"' # Lower Pane
+---| '"k"' # Upper Pane
+---| '"l"' # Right Pane
+
+---Configure the plugin
+---@param opts Config
+---@usage [[
+----- With default config
+---require('Navigator').setup()
+---
+----- With custom config
+---require('Navigator').setup({
+---    auto_save = 'current'
+---    disable_on_zoom = true
+---})
+---@usage ]]
+function Nav.setup(opts)
+    n.setup(opts)
+end
 
 ---Go to left split/pane
-function N.left()
+---@usage [[
+---require('Navigator').left()
+---
+----- With keybinding
+---vim.keymap.set({'n', 't'}, '<A-h>', require('Navigator').left)
+---@usage ]]
+function Nav.left()
     n.navigate('h')
 end
 
----Go to above split/pane
-function N.up()
+---Go to upper split/pane
+---@usage [[
+---require('Navigator').up()
+---
+----- With keybinding
+---vim.keymap.set({'n', 't'}, '<A-k>', require('Navigator').up)
+---@usage ]]
+function Nav.up()
     n.navigate('k')
 end
 
 ---Go to right split/pane
-function N.right()
+---@usage [[
+---require('Navigator').right()
+---
+----- With keybinding
+---vim.keymap.set({'n', 't'}, '<A-l>', require('Navigator').right)
+---@usage ]]
+function Nav.right()
     n.navigate('l')
 end
 
----Go to below split/pane
-function N.down()
+---Go to down split/pane
+---@usage [[
+---require('Navigator').down()
+---
+----- With keybinding
+---vim.keymap.set({'n', 't'}, '<A-j>', require('Navigator').down)
+---@usage ]]
+function Nav.down()
     n.navigate('j')
 end
 
 ---Go to previous split/pane
-function N.previous()
+---@usage [[
+---require('Navigator').previous()
+---
+----- With keybinding
+---vim.keymap.set({'n', 't'}, '<A-p>', require('Navigator').previous)
+---@usage ]]
+function Nav.previous()
     n.navigate('p')
 end
 
-return N
+return Nav

lua/Navigator/init.lua

@@ -1,3 +1,12 @@
+---@mod navigator.tmux Tmux navigator
+---@brief [[
+---This module provides navigation and interaction for Tmux, and uses |navigator.vi|
+---as a base class. This is used automatically when tmux is detected on host
+---system but can also be used to manually override the mux.
+---Read also: https://github.com/numToStr/Navigator.nvim/wiki/Tmux-Integration
+---@brief ]]
+
+---@private
 ---@class Tmux: Vi
 ---@field private pane string
 ---@field private direction table<Direction, string>
@@ -6,6 +15,15 @@ local Tmux = require('Navigator.mux.vi'):new()
 
 ---Creates a new Tmux navigator instance
 ---@return Tmux
+---@usage [[
+---local ok, tmux = pcall(function()
+---    return require('Navigator.mux.tmux'):new()
+---end)
+---
+---require('Navigator').setup({
+---    mux = ok and tmux or 'auto'
+---})
+---@usage ]]
 function Tmux:new()
     local instance = os.getenv('TMUX')
     local pane = os.getenv('TMUX_PANE')
@@ -34,7 +52,7 @@ function Tmux:zoomed()
 end
 
 ---Switch pane in tmux
----@param direction Direction
+---@param direction Direction See |navigator.api.Direction|
 ---@return Tmux
 function Tmux:navigate(direction)
     self.execute(string.format("select-pane -t '%s' -%s", self.pane, self.direction[direction]))

lua/Navigator/mux/tmux.lua

@@ -1,26 +1,35 @@
+---@mod navigator.vi Neovim navigator
+---@brief [[
+---This module provides navigation and interaction for Neovim. This also acts
+---as a base class for other multiplexer implementation.
+---
+---Read: https://github.com/numToStr/Navigator.nvim/wiki/Custom-Multiplexer
+---@brief ]]
+
+---@private
 ---@class Vi
 local Vi = {}
+local cmd = vim.api.nvim_command
 
 ---Creates new Neovim navigator instance
----NOTE: This can be used as a base for other navigators
 ---@return Vi
 function Vi:new()
     self.__index = self
     return setmetatable({}, self)
 end
 
 ---Checks whether neovim is maximized
----NOTE: This is only useful for `tmux`, for other mux(s) return false would suffice
+---NOTE: For neovim, this always returns `false`.
 ---@return boolean
 function Vi.zoomed()
     return false
 end
 
 ---Navigate inside neovim
----@param direction Direction
+---@param direction Direction See |navigator.api.Direction|
 ---@return Vi
 function Vi:navigate(direction)
-    vim.api.nvim_command('wincmd ' .. direction)
+    cmd('wincmd ' .. direction)
     return self
 end
 

lua/Navigator/mux/vi.lua

@@ -1,10 +1,29 @@
+---@mod navigator.wezterm WezTerm navigator
+---@brief [[
+---This module provides navigation and interaction for WezTerm, and uses |navigator.vi|
+---as a base class. This is used automatically when wezterm is detected on host system
+---but can also be used to manually override the mux.
+---
+---Read also: https://github.com/numToStr/Navigator.nvim/wiki/WezTerm-Integration
+---@brief ]]
+
+---@private
 ---@class WezTerm: Vi
 ---@field private direction table<Direction, string>
 ---@field private execute fun(arg: string): unknown
 local WezTerm = require('Navigator.mux.vi'):new()
 
 ---Creates a new WezTerm navigator instance
 ---@return WezTerm
+---@usage [[
+---local ok, wezterm = pcall(function()
+---    return require('Navigator.mux.wezterm'):new()
+---end)
+---
+---require('Navigator').setup({
+---    mux = ok and wezterm or 'auto'
+---})
+---@usage ]]
 function WezTerm:new()
     assert(os.getenv('TERM_PROGRAM') == 'WezTerm', '[Navigator] WezTerm is not running!')
 
@@ -23,7 +42,7 @@ function WezTerm:new()
 end
 
 ---Switch pane in wezterm
----@param direction Direction
+---@param direction Direction See |navigator.api.Direction|
 ---@return WezTerm
 function WezTerm:navigate(direction)
     self.execute(string.format('activate-pane-direction %s', self.direction[direction]))

lua/Navigator/mux/wezterm.lua

@@ -1,7 +1,16 @@
 local A = vim.api
 local cmd = A.nvim_command
 
----Loads mux
+---State and defaults
+---@class Nav
+---@field last_pane boolean
+---@field config? Config
+local N = {
+    last_pane = false,
+    config = nil,
+}
+
+---Detect and load correct mux
 ---@return Vi
 local function load_mux()
     local ok_tmux, tmux = pcall(function()
@@ -19,25 +28,10 @@ local function load_mux()
     return require('Navigator.mux.vi'):new()
 end
 
----@alias Direction 'p'|'h'|'k'|'l'|'j'
-
----@class Config
----@field auto_save? '"current"'|'"all"' Save modified buffer(s) when moving to mux
----@field disable_on_zoom boolean Disable navigation when the current mux pane is zoomed in
----@field mux 'auto'|Vi Multiplexer to use
-
----State and defaults
----@class Nav
----@field last_pane boolean
----@field config? Config
-local N = {
-    last_pane = false,
-    config = nil,
-}
-
 ---For setting up the plugin with the user provided options
 ---@param opts Config
 function N.setup(opts)
+    ---@type Config
     local config = {
         disable_on_zoom = false,
         auto_save = nil,
@@ -65,7 +59,7 @@ end
 ---Checks whether we need to move to the nearby mux pane
 ---@param at_edge boolean
 ---@return boolean
-function N.back_to_mux(at_edge)
+local function back_to_mux(at_edge)
     if N.config.disable_on_zoom and N.config.mux:zoomed() then
         return false
     end
@@ -89,7 +83,7 @@ function N.navigate(direction)
     -- then we can assume that we hit the edge
     -- there is mux pane besided the edge
     -- So we can navigate to the mux pane
-    if N.back_to_mux(at_edge) then
+    if back_to_mux(at_edge) then
         N.config.mux:navigate(direction)
 
         local save = N.config.auto_save