🐈 vimCATS 📖

What?

Installation

cargo install vimcats --features=cli

LuaCATS

Usage

vimcats /path/to/{first,second,third}.lua > doc/PLUGIN_NAME.txt

CLI

vimcats
USAGE:
 vimcats [FLAGS] [OPTIONS] <FILES>...
ARGS:
 <FILES>... Path to lua files
FLAGS:
 -h, --help Print help information
 -v, --version Print version information
 -M, --no-modeline Don't print modeline at the end
 -f, --prefix-func Prefix function name with ---@mod name
 -a, --prefix-alias Prefix ---@alias tag with return/---@mod name
 -c, --prefix-class Prefix ---@class tag with return/---@mod name
 -t, --prefix-type Prefix ---@type tag with ---@mod name
 --expand-opt Expand '?' (optional) to 'nil' type
OPTIONS:
 -i, --indent <u8> Controls the indent width [default: 4]
 -l, --layout <layout> Vimdoc text layout [default: 'default']
 - "default" : Default layout
 - "compact[:n=0]" : Aligns [desc] with <type>
 and uses {n}, if provided, to indent the
 following new lines. This option only
 affects ---@field and ---@param tags
 - "mini[:n=0]" : Aligns [desc] from the start
 and uses {n}, if provided, to indent the
 following new lines. This option affects
 ---@field, ---@param and ---@return tags
USAGE:
 vimcats /path/to/first.lua /path/to/second.lua > doc/PLUGIN_NAME.txt
 vimcats -c -a /path/to/{first,second,third}.lua > doc/PLUGIN_NAME.txt
 vimcats --layout compact:2 /path/to/plugin.lua > doc/PLUGIN_NAME.txt
NOTES:
 - The order of parsing + rendering is relative to the given files

CI

name: vimcats
on: [push]
env:
 PLUGIN_NAME: plugin-name
jobs:
 docs:
 runs-on: ubuntu-latest
 name: luaCATS to vimdoc
 steps:
 - uses: actions/checkout@v4
 - name: Install Rust
 uses: dtolnay/rust-toolchain@master
 - name: Install vimcats
 run: cargo install vimcats --features=cli
 - name: Generate docs
 run: vimcats [args] <path> > 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 vimdoc"
 file_pattern: doc/*.txt

Nix flake

Note

You will likely want to ajust the flake to be used with multiple systems.

{ 
 inputs = {
 git-hooks.url = "github:cachix/git-hooks.nix";
 vimcats.url = "github:mrcjkb/vimcats";
 };
 
 outputs = {
 self,
 nixpkgs,
 git-hooks,
 vimcats,
 ...
 }: let
 system = "x86_64-linux";
 pkgs = nixpkgs.legacyPackages.${system};
 docgen = final.writeShellApplication {
 name = "docgen";
 runtimeInputs = [
 inputs.vimcats.packages.${final.system}.default
 ];
 text = ''
 mkdir -p doc
 vimcats [args] <path> > doc/<plugin-name>.txt
 '';
 };
 git-hooks-check = git-hooks.lib.${system}.run {
 src = self;
 hooks = {
 docgen = {
 enable = true;
 name = "docgen";
 entry = "${pkgs.docgen}/bin/docgen";
 files = "\\.(lua)$";
 pass_filenames = false;
 };
 };
 };
 in {
 devShells.${system}.default = {
 pkgs.mkShell {
 buildInputs = [
 docgen
 ];
 shellHook = ''
 # Installs a docgen pre-commit hook
 ${git-hooks-check.shellHook}
 '';
 };
 };
 checks.${system} = {
 inherit git-hooks-check;
 };
 };
}

Credits

License