From 25b3d917b944492206a3aeab4626d27c40457d13 Mon Sep 17 00:00:00 2001 From: Marc Jakobi Date: Thu, 22 Aug 2024 11:52:10 +0200 Subject: [PATCH] feat: vimdoc --- doc/lz.n.txt | 143 +++++++++++++++++++++++++++++++++++++++++++++ flake.lock | 130 ++++++++++++++++++++++++++++++++--------- flake.nix | 13 ++++- lua/lz/n/meta.lua | 126 ++++++++++++++++++++------------------- nix/ci-overlay.nix | 16 ++++- 5 files changed, 334 insertions(+), 94 deletions(-) create mode 100644 doc/lz.n.txt diff --git a/doc/lz.n.txt b/doc/lz.n.txt new file mode 100644 index 0000000..544b86b --- /dev/null +++ b/doc/lz.n.txt @@ -0,0 +1,143 @@ +============================================================================== + *lz.n* + +M.register_handler() *M.register_handler* + + +M.trigger_load({plugins}) *M.trigger_load* + Accepts plugin names (`string | string[]`, when called in another + plugin's hook), or |lz.n.Plugin| items (when called by a |lz.n.Handler|). + If called with a plugin name, it will use the registered + handlers' `lookup` functions to search for a plugin to load + (loading the first one it finds). + Once a plugin has been loaded, it will be removed from all handlers (via `del`). + As a result, calling `trigger_load` with a plugin name is idempotent. + + Parameters: ~ + {plugins} (string|lz.n.Plugin|string[]|lz.n.Plugin[]) + + +M.load() *M.load* + @overload fun(spec: lz.n.Spec) + @overload fun(import: string) + + +M.lookup({name}) *M.lookup* + Lookup a plugin that is pending to be loaded by name. + + Parameters: ~ + {name} (string) @return lz.n.Plugin? + + +============================================================================== +lz.n type definitions *lz.n.types* + +lz.n.PluginBase *lz.n.PluginBase* + + Fields: ~ + {enabled?} (boolean|fun():boolean) + Whether to enable this plugin. Useful to disable plugins under certain conditions. + {priority?} (number) + Only useful for lazy=false plugins to force loading certain plugins first. + Default priority is 50 + {load?} (fun(name:string)) + Set this to override the `load` function for an individual plugin. + Defaults to `vim.g.lz_n.load()`, see |lz.n.Config|. + + +lz.n.Event *lz.n.Event* + + Type: ~ + {id:string,event:string[]|string,pattern?:string[]|string} + + +lz.n.EventSpec *lz.n.EventSpec* + + Type: ~ + string|{event?:string|string[],pattern?:string|string[]}|string[] + + +lz.n.PluginHooks *lz.n.PluginHooks* + + Fields: ~ + {beforeAll?} (fun(self:lz.n.Plugin)) Will be run before loading any plugins + {before?} (fun(self:lz.n.Plugin)) Will be run before loading this plugin + {after?} (fun(self:lz.n.Plugin)) Will be executed after loading this plugin + + +lz.n.PluginHandlers *lz.n.PluginHandlers* + + Fields: ~ + {event?} (lz.n.Event[]) + {keys?} (lz.n.Keys[]) + {cmd?} (string[]) + {colorscheme?} (string[]) + + +lz.n.PluginSpecHandlers *lz.n.PluginSpecHandlers* + + Fields: ~ + {event?} (string|lz.n.EventSpec[]) + Load a plugin on one or more |autocmd-events|. + {cmd?} (string[]|string) + Load a plugin on one or more |user-commands|. + {ft?} (string[]|string) + Load a plugin on one or more |FileType| events. + {keys?} (string|string[]|lz.n.KeysSpec[]) + Load a plugin on one or more |key-mapping|s. + {colorscheme?} (string[]|string) + Load a plugin on one or more |colorscheme| events. + + +lz.n.KeysBase : vim *lz.n.KeysBase* + + +lz.n.KeysSpec : lz *lz.n.KeysSpec* + + +lz.n.Keys : lz *lz.n.Keys* + + +lz.n.Plugin : lz *lz.n.Plugin* + + +lz.n.PluginSpec : lz *lz.n.PluginSpec* + + +lz.n.SpecImport *lz.n.SpecImport* + The plugin name (not its main module), e.g. "sweetie.nvim" + @field [1] string + + Fields: ~ + {import} (string) spec module to import + {enabled?} (boolean|fun():boolean) + + +lz.n.Spec *lz.n.Spec* + + Type: ~ + lz.n.PluginSpec|lz.n.SpecImport|lz.n.Spec[] + + +lz.n.Config *lz.n.Config* + + Fields: ~ + {load?} (fun(name:string)) + Callback to load a plugin. + Takes the plugin name (not the module name). Defaults to |packadd| if not set. + + +lz.n.Handler *lz.n.Handler* + + Fields: ~ + {spec_field} (string) + The |lz.n.PluginSpec| field used to configure this handler. + {add} (fun(plugin:lz.n.Plugin)) + Add a plugin to this handler. + {del} (fun(name:string)) + Remove a plugin from this handler by name. + {lookup} (fun(name:string):lz.n.Plugin) + Lookup a plugin by name. + + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/flake.lock b/flake.lock index 56a36de..91f5be6 100755 --- a/flake.lock +++ b/flake.lock @@ -1,5 +1,24 @@ { "nodes": { + "cats-doc": { + "inputs": { + "flake-parts": "flake-parts", + "nixpkgs": "nixpkgs" + }, + "locked": { + "lastModified": 1719860562, + "narHash": "sha256-zB0xoHts0+K8dO6Gbm+v9bjKHA5POdStdBUjomZTikY=", + "owner": "mrcjkb", + "repo": "cats-doc", + "rev": "8c054023347c9aa577dd3bcbed26e6e0a88900ec", + "type": "github" + }, + "original": { + "owner": "mrcjkb", + "repo": "cats-doc", + "type": "github" + } + }, "flake-compat": { "flake": false, "locked": { @@ -84,6 +103,24 @@ "inputs": { "nixpkgs-lib": "nixpkgs-lib" }, + "locked": { + "lastModified": 1696343447, + "narHash": "sha256-B2xAZKLkkeRFG5XcHHSXXcP7To9Xzr59KXeZiRf4vdQ=", + "owner": "hercules-ci", + "repo": "flake-parts", + "rev": "c9afaba3dfa4085dbd2ccb38dfade5141e33d9d4", + "type": "github" + }, + "original": { + "owner": "hercules-ci", + "repo": "flake-parts", + "type": "github" + } + }, + "flake-parts_2": { + "inputs": { + "nixpkgs-lib": "nixpkgs-lib_2" + }, "locked": { "lastModified": 1722555600, "narHash": "sha256-XOQkdLafnb/p9ij77byFQjDf5m5QYl9b2REiVClC+x4=", @@ -98,9 +135,9 @@ "type": "github" } }, - "flake-parts_2": { + "flake-parts_3": { "inputs": { - "nixpkgs-lib": "nixpkgs-lib_2" + "nixpkgs-lib": "nixpkgs-lib_3" }, "locked": { "lastModified": 1717285511, @@ -116,9 +153,9 @@ "type": "github" } }, - "flake-parts_3": { + "flake-parts_4": { "inputs": { - "nixpkgs-lib": "nixpkgs-lib_3" + "nixpkgs-lib": "nixpkgs-lib_4" }, "locked": { "lastModified": 1722555600, @@ -134,7 +171,7 @@ "type": "github" } }, - "flake-parts_4": { + "flake-parts_5": { "inputs": { "nixpkgs-lib": [ "neorocks", @@ -156,7 +193,7 @@ "type": "github" } }, - "flake-parts_5": { + "flake-parts_6": { "inputs": { "nixpkgs-lib": [ "neorocks", @@ -180,8 +217,8 @@ }, "gen-luarc": { "inputs": { - "flake-parts": "flake-parts_2", - "nixpkgs": "nixpkgs" + "flake-parts": "flake-parts_3", + "nixpkgs": "nixpkgs_2" }, "locked": { "lastModified": 1718922730, @@ -201,7 +238,7 @@ "inputs": { "flake-compat": "flake-compat_2", "gitignore": "gitignore", - "nixpkgs": "nixpkgs_2", + "nixpkgs": "nixpkgs_3", "nixpkgs-stable": "nixpkgs-stable" }, "locked": { @@ -315,7 +352,7 @@ }, "hercules-ci-effects": { "inputs": { - "flake-parts": "flake-parts_5", + "flake-parts": "flake-parts_6", "nixpkgs": [ "neorocks", "neovim-nightly", @@ -339,10 +376,10 @@ "neorocks": { "inputs": { "flake-compat": "flake-compat", - "flake-parts": "flake-parts_3", + "flake-parts": "flake-parts_4", "git-hooks": "git-hooks", "neovim-nightly": "neovim-nightly", - "nixpkgs": "nixpkgs_4" + "nixpkgs": "nixpkgs_5" }, "locked": { "lastModified": 1723872620, @@ -361,11 +398,11 @@ "neovim-nightly": { "inputs": { "flake-compat": "flake-compat_3", - "flake-parts": "flake-parts_4", + "flake-parts": "flake-parts_5", "git-hooks": "git-hooks_2", "hercules-ci-effects": "hercules-ci-effects", "neovim-src": "neovim-src", - "nixpkgs": "nixpkgs_3" + "nixpkgs": "nixpkgs_4" }, "locked": { "lastModified": 1723796332, @@ -399,21 +436,39 @@ }, "nixpkgs": { "locked": { - "lastModified": 1718714799, - "narHash": "sha256-FUZpz9rg3gL8NVPKbqU8ei1VkPLsTIfAJ2fdAf5qjak=", - "owner": "nixos", + "lastModified": 1697379843, + "narHash": "sha256-RcnGuJgC2K/UpTy+d32piEoBXq2M+nVFzM3ah/ZdJzg=", + "owner": "NixOS", "repo": "nixpkgs", - "rev": "c00d587b1a1afbf200b1d8f0b0e4ba9deb1c7f0e", + "rev": "12bdeb01ff9e2d3917e6a44037ed7df6e6c3df9d", "type": "github" }, "original": { - "owner": "nixos", - "ref": "nixos-unstable", + "owner": "NixOS", + "ref": "nixpkgs-unstable", "repo": "nixpkgs", "type": "github" } }, "nixpkgs-lib": { + "locked": { + "dir": "lib", + "lastModified": 1696019113, + "narHash": "sha256-X3+DKYWJm93DRSdC5M6K5hLqzSya9BjibtBsuARoPco=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "f5892ddac112a1e9b3612c39af1b72987ee5783a", + "type": "github" + }, + "original": { + "dir": "lib", + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "nixpkgs-lib_2": { "locked": { "lastModified": 1722555339, "narHash": "sha256-uFf2QeW7eAHlYXuDktm9c25OxOyCoUOQmh5SZ9amE5Q=", @@ -425,7 +480,7 @@ "url": "https://github.com/NixOS/nixpkgs/archive/a5d394176e64ab29c852d03346c1fc9b0b7d33eb.tar.gz" } }, - "nixpkgs-lib_2": { + "nixpkgs-lib_3": { "locked": { "lastModified": 1717284937, "narHash": "sha256-lIbdfCsf8LMFloheeE6N31+BMIeixqyQWbSr2vk79EQ=", @@ -437,7 +492,7 @@ "url": "https://github.com/NixOS/nixpkgs/archive/eb9ceca17df2ea50a250b6b27f7bf6ab0186f198.tar.gz" } }, - "nixpkgs-lib_3": { + "nixpkgs-lib_4": { "locked": { "lastModified": 1722555339, "narHash": "sha256-uFf2QeW7eAHlYXuDktm9c25OxOyCoUOQmh5SZ9amE5Q=", @@ -482,6 +537,22 @@ } }, "nixpkgs_2": { + "locked": { + "lastModified": 1718714799, + "narHash": "sha256-FUZpz9rg3gL8NVPKbqU8ei1VkPLsTIfAJ2fdAf5qjak=", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "c00d587b1a1afbf200b1d8f0b0e4ba9deb1c7f0e", + "type": "github" + }, + "original": { + "owner": "nixos", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "nixpkgs_3": { "locked": { "lastModified": 1719082008, "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=", @@ -497,7 +568,7 @@ "type": "github" } }, - "nixpkgs_3": { + "nixpkgs_4": { "locked": { "lastModified": 1723703277, "narHash": "sha256-nk0RaUB5f68BwtXAYy3WAjqFhVKqIl9Z89RGycTa2vk=", @@ -513,7 +584,7 @@ "type": "github" } }, - "nixpkgs_4": { + "nixpkgs_5": { "locked": { "lastModified": 1723703277, "narHash": "sha256-nk0RaUB5f68BwtXAYy3WAjqFhVKqIl9Z89RGycTa2vk=", @@ -529,7 +600,7 @@ "type": "github" } }, - "nixpkgs_5": { + "nixpkgs_6": { "locked": { "lastModified": 1723856861, "narHash": "sha256-OTDg91+Zzs2SpU3csK4xVdSQFoG8cK1lNUwKmTqERyE=", @@ -545,7 +616,7 @@ "type": "github" } }, - "nixpkgs_6": { + "nixpkgs_7": { "locked": { "lastModified": 1719082008, "narHash": "sha256-jHJSUH619zBQ6WdC21fFAlDxHErKVDJ5fpN0Hgx4sjs=", @@ -565,7 +636,7 @@ "inputs": { "flake-compat": "flake-compat_5", "gitignore": "gitignore_3", - "nixpkgs": "nixpkgs_6", + "nixpkgs": "nixpkgs_7", "nixpkgs-stable": "nixpkgs-stable_2" }, "locked": { @@ -584,10 +655,11 @@ }, "root": { "inputs": { - "flake-parts": "flake-parts", + "cats-doc": "cats-doc", + "flake-parts": "flake-parts_2", "gen-luarc": "gen-luarc", "neorocks": "neorocks", - "nixpkgs": "nixpkgs_5", + "nixpkgs": "nixpkgs_6", "pre-commit-hooks": "pre-commit-hooks" } } diff --git a/flake.nix b/flake.nix index 4c1def3..7d91ad7 100755 --- a/flake.nix +++ b/flake.nix @@ -13,6 +13,8 @@ neorocks.url = "github:nvim-neorocks/neorocks"; gen-luarc.url = "github:mrcjkb/nix-gen-luarc-json"; + + cats-doc.url = "github:mrcjkb/cats-doc"; }; outputs = inputs @ { @@ -22,6 +24,7 @@ pre-commit-hooks, neorocks, gen-luarc, + cats-doc, ... }: let name = "lz.n"; @@ -45,7 +48,7 @@ ... }: let ci-overlay = import ./nix/ci-overlay.nix { - inherit self; + inherit self inputs; plugin-name = name; }; @@ -86,6 +89,13 @@ "CHANGELOG.md" ]; }; + docgen = { + enable = true; + name = "docgen"; + entry = "${pkgs.docgen}/bin/docgen"; + files = "\\.(lua)$"; + pass_filenames = false; + }; }; }; @@ -100,6 +110,7 @@ ++ (with pkgs; [ lua-language-server busted-nlua + docgen ]); }; in { diff --git a/lua/lz/n/meta.lua b/lua/lz/n/meta.lua index 9703f57..1971875 100644 --- a/lua/lz/n/meta.lua +++ b/lua/lz/n/meta.lua @@ -1,106 +1,110 @@ ----@meta -error("Cannot import a meta module") +---@mod lz.n.types lz.n type definitions ---- @class lz.n.PluginBase +---@class lz.n.PluginBase --- --- Whether to enable this plugin. Useful to disable plugins under certain conditions. ---- @field enabled? boolean|(fun():boolean) +---@field enabled? boolean|(fun():boolean) --- --- Only useful for lazy=false plugins to force loading certain plugins first. --- Default priority is 50 ---- @field priority? number +---@field priority? number --- --- Set this to override the `load` function for an individual plugin. --- Defaults to `vim.g.lz_n.load()`, see |lz.n.Config|. ---- @field load? fun(name: string) +---@field load? fun(name: string) ---- @alias lz.n.Event {id:string, event:string[]|string, pattern?:string[]|string} ---- @alias lz.n.EventSpec string|{event?:string|string[], pattern?:string|string[]}|string[] +---@alias lz.n.Event {id:string, event:string[]|string, pattern?:string[]|string} +---@alias lz.n.EventSpec string|{event?:string|string[], pattern?:string|string[]}|string[] ---- @class lz.n.PluginHooks ---- @field beforeAll? fun(self:lz.n.Plugin) Will be run before loading any plugins ---- @field before? fun(self:lz.n.Plugin) Will be run before loading this plugin ---- @field after? fun(self:lz.n.Plugin) Will be executed after loading this plugin +---@class lz.n.PluginHooks +---@field beforeAll? fun(self:lz.n.Plugin) Will be run before loading any plugins +---@field before? fun(self:lz.n.Plugin) Will be run before loading this plugin +---@field after? fun(self:lz.n.Plugin) Will be executed after loading this plugin ---- @class lz.n.PluginHandlers ---- @field event? lz.n.Event[] ---- @field keys? lz.n.Keys[] ---- @field cmd? string[] ---- @field colorscheme? string[] +---@class lz.n.PluginHandlers +---@field event? lz.n.Event[] +---@field keys? lz.n.Keys[] +---@field cmd? string[] +---@field colorscheme? string[] ---- @class lz.n.PluginSpecHandlers +---@class lz.n.PluginSpecHandlers --- --- Load a plugin on one or more |autocmd-events|. ---- @field event? string|lz.n.EventSpec[] +---@field event? string|lz.n.EventSpec[] --- --- Load a plugin on one or more |user-commands|. ---- @field cmd? string[]|string +---@field cmd? string[]|string --- --- Load a plugin on one or more |FileType| events. ---- @field ft? string[]|string +---@field ft? string[]|string --- --- Load a plugin on one or more |key-mapping|s. ---- @field keys? string|string[]|lz.n.KeysSpec[] +---@field keys? string|string[]|lz.n.KeysSpec[] --- --- Load a plugin on one or more |colorscheme| events. ---- @field colorscheme? string[]|string - ---- @class lz.n.KeysBase: vim.keymap.set.Opts ---- @field desc? string ---- @field noremap? boolean ---- @field remap? boolean ---- @field expr? boolean ---- @field nowait? boolean ---- @field ft? string|string[] - ---- @class lz.n.KeysSpec: lz.n.KeysBase ---- @field [1] string lhs ---- @field [2]? string|fun()|false rhs ---- @field mode? string|string[] - ---- @class lz.n.Keys: lz.n.KeysBase ---- @field lhs string lhs ---- @field rhs? string|fun() rhs ---- @field mode? string ---- @field id string ---- @field name string - ---- @class lz.n.Plugin: lz.n.PluginBase,lz.n.PluginHandlers,lz.n.PluginHooks +---@field colorscheme? string[]|string + +---@class lz.n.KeysBase: vim.keymap.set.Opts +---@field desc? string +---@field noremap? boolean +---@field remap? boolean +---@field expr? boolean +---@field nowait? boolean +---@field ft? string|string[] + +---@class lz.n.KeysSpec: lz.n.KeysBase +---@field [1] string lhs +---@field [2]? string|fun()|false rhs +---@field mode? string|string[] + +---@class lz.n.Keys: lz.n.KeysBase +---@field lhs string lhs +---@field rhs? string|fun() rhs +---@field mode? string +---@field id string +---@field name string + +---@class lz.n.Plugin: lz.n.PluginBase,lz.n.PluginHandlers,lz.n.PluginHooks --- The plugin name (not its main module), e.g. "sweetie.nvim" ---- @field name string +---@field name string --- --- Whether to lazy-load this plugin. Defaults to `false`. ---- @field lazy? boolean +---@field lazy? boolean ---- @class lz.n.PluginSpec: lz.n.PluginBase,lz.n.PluginSpecHandlers,lz.n.PluginHooks +---@class lz.n.PluginSpec: lz.n.PluginBase,lz.n.PluginSpecHandlers,lz.n.PluginHooks --- The plugin name (not its main module), e.g. "sweetie.nvim" ---- @field [1] string +---@field [1] string ---- @class lz.n.SpecImport ---- @field import string spec module to import ---- @field enabled? boolean|(fun():boolean) +---@class lz.n.SpecImport +---@field import string spec module to import +---@field enabled? boolean|(fun():boolean) ---- @alias lz.n.Spec lz.n.PluginSpec | lz.n.SpecImport | lz.n.Spec[] +---@alias lz.n.Spec lz.n.PluginSpec | lz.n.SpecImport | lz.n.Spec[] ---- @class lz.n.Config +---@class lz.n.Config --- --- Callback to load a plugin. --- Takes the plugin name (not the module name). Defaults to |packadd| if not set. ---- @field load? fun(name: string) +---@field load? fun(name: string) ---- @class lz.n.Handler +---@class lz.n.Handler --- --- The |lz.n.PluginSpec| field used to configure this handler. ---- @field spec_field string +---@field spec_field string --- --- Add a plugin to this handler. ---- @field add fun(plugin: lz.n.Plugin) +---@field add fun(plugin: lz.n.Plugin) --- --- Remove a plugin from this handler by name. ---- @field del fun(name: string) +---@field del fun(name: string) --- --- Lookup a plugin by name. ---- @field lookup fun(name: string): lz.n.Plugin? +---@field lookup fun(name: string): lz.n.Plugin? ---- @type lz.n.Config +---@type lz.n.Config vim.g.lz_n = vim.g.lz_n + +error("Cannot import a meta module") + +local M = {} +return M diff --git a/nix/ci-overlay.nix b/nix/ci-overlay.nix index d172b26..f49065a 100755 --- a/nix/ci-overlay.nix +++ b/nix/ci-overlay.nix @@ -1,10 +1,9 @@ # Add flake.nix test inputs as arguments here { self, + inputs, plugin-name, -}: final: prev: -with final.lib; -with final.stdenv; let +}: final: prev: let nvim-nightly = final.neovim-nightly; mkNeorocksTest = { @@ -40,10 +39,21 @@ with final.stdenv; let cp -r tests $out ''; }; + docgen = final.writeShellApplication { + name = "docgen"; + runtimeInputs = [ + inputs.cats-doc.packages.${final.system}.default + ]; + text = '' + mkdir -p doc + lemmy-help lua/lz/n/{init,meta}.lua > doc/lz.n.txt + ''; + }; in { nvim-stable-tests = mkNeorocksTest {name = "neovim-stable-tests";}; nvim-nightly-tests = mkNeorocksTest { name = "neovim-nightly-tests"; nvim = nvim-nightly; }; + inherit docgen; }