{"id":14981772,"url":"https://github.com/mrcjkb/vimcats","last_synced_at":"2025-10-29T08:33:56.152Z","repository":{"id":215620895,"uuid":"706871243","full_name":"mrcjkb/vimcats","owner":"mrcjkb","description":"A CLI to generate vim/nvim help doc from LuaCATS. Forked from lemmy-help.","archived":false,"fork":false,"pushed_at":"2024-09-11T09:00:11.000Z","size":338,"stargazers_count":18,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-02T00:24:42.484Z","etag":null,"topics":["doc","help","lua","luacats","vimdoc"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrcjkb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mrcjkb"]}},"created_at":"2023-10-18T19:25:10.000Z","updated_at":"2024-12-31T21:38:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"628429ef-11b9-4d55-9eff-ea673c9128de","html_url":"https://github.com/mrcjkb/vimcats","commit_stats":{"total_commits":205,"total_committers":6,"mean_commits":"34.166666666666664","dds":"0.42439024390243907","last_synced_commit":"fd213ad22ffbfff87899c872752a1c92814c93fa"},"previous_names":["mrcjkb/lemmy-help","mrcjkb/vimcats"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrcjkb%2Fvimcats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrcjkb%2Fvimcats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrcjkb%2Fvimcats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrcjkb%2Fvimcats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrcjkb","download_url":"https://codeload.github.com/mrcjkb/vimcats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238795471,"owners_count":19531752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doc","help","lua","luacats","vimdoc"],"created_at":"2024-09-24T14:04:14.166Z","updated_at":"2025-10-29T08:33:55.695Z","avatar_url":"https://github.com/mrcjkb.png","language":"Rust","funding_links":["https://github.com/sponsors/mrcjkb"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e:cat2: vimCATS :book:\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003csup\u003eA CLI to generate vimdoc from LuaCATS. Forked from lemmy-help.\u003c/sup\u003e\u003c/p\u003e\n\n\u003c!-- TODO: Update gif --\u003e\n![vimcats](https://user-images.githubusercontent.com/24727447/164423469-b26fea39-2ef7-497c-8156-5a4c01bc30f8.gif \"Generating help docs\")\n\n### What?\n\n`vimcats` is a LuaCATS parser as well as a CLI\nwhich takes that parsed tree and converts it into vim help docs.\n\n### Installation\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/vimcats.svg)](https://repology.org/project/vimcats/versions)\n\n- Using `cargo`\n\n```bash\ncargo install vimcats --features=cli\n```\n\n### LuaCATS\n\nTo properly generate docs you should follow the luaCATS spec.\nThe parser is capable of parsing most (not all) of the LuaCATS syntax.\nYou can read the following doc which can give you an idea on how to\nproperly write LuaCATS annotations.\n\n- [Writing LuaCATS annotations](./luaCATS.md)\n\n### Usage\n\nUsing the CLI is simple just give it the path to the lua files;\nit will parse them and prints help doc to `stdout`.\n\n```bash\nvimcats /path/to/{first,second,third}.lua \u003e doc/PLUGIN_NAME.txt\n```\n\n### CLI\n\n```text\nvimcats\n\nUSAGE:\n    vimcats [FLAGS] [OPTIONS] \u003cFILES\u003e...\n\nARGS:\n    \u003cFILES\u003e...                  Path to lua files\n\nFLAGS:\n    -h, --help                  Print help information\n    -v, --version               Print version information\n    -M, --no-modeline           Don't print modeline at the end\n    -f, --prefix-func           Prefix function name with ---@mod name\n    -a, --prefix-alias          Prefix ---@alias tag with return/---@mod name\n    -c, --prefix-class          Prefix ---@class tag with return/---@mod name\n    -t, --prefix-type           Prefix ---@type tag with ---@mod name\n        --expand-opt            Expand '?' (optional) to 'nil' type\n\nOPTIONS:\n    -i, --indent \u003cu8\u003e           Controls the indent width [default: 4]\n    -l, --layout \u003clayout\u003e       Vimdoc text layout [default: 'default']\n                                - \"default\" : Default layout\n                                - \"compact[:n=0]\" : Aligns [desc] with \u003ctype\u003e\n                                  and uses {n}, if provided, to indent the\n                                  following new lines. This option only\n                                  affects ---@field and ---@param tags\n                                - \"mini[:n=0]\" : Aligns [desc] from the start\n                                  and uses {n}, if provided, to indent the\n                                  following new lines. This option affects\n                                  ---@field, ---@param and ---@return tags\n\nUSAGE:\n    vimcats /path/to/first.lua /path/to/second.lua \u003e doc/PLUGIN_NAME.txt\n    vimcats -c -a /path/to/{first,second,third}.lua \u003e doc/PLUGIN_NAME.txt\n    vimcats --layout compact:2 /path/to/plugin.lua \u003e doc/PLUGIN_NAME.txt\n\nNOTES:\n    - The order of parsing + rendering is relative to the given files\n```\n\n### CI\n\n```yaml\nname: vimcats\n\non: [push]\n\nenv:\n  PLUGIN_NAME: plugin-name\n\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    name: luaCATS to vimdoc\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Install Rust\n        uses: dtolnay/rust-toolchain@master\n\n      - name: Install vimcats\n        run: cargo install vimcats --features=cli\n\n      - name: Generate docs\n        run: vimcats [args] \u003cpath\u003e \u003e doc/${{env.PLUGIN_NAME}}.txt\n\n      - name: Commit\n        uses: stefanzweifel/git-auto-commit-action@v4\n        with:\n          branch: ${{ github.head_ref }}\n          commit_message: \"chore(docs): auto-generate vimdoc\"\n          file_pattern: doc/*.txt\n```\n\n### Nix flake\n\nThis project provides a flake so you can use it with frameworks\nlike [git-hooks.nix](https://github.com/cachix/git-hooks.nix).\n\nHere is basic example:\n\n\u003e [!NOTE]\n\u003e\n\u003e You will likely want to ajust the flake to be used\n\u003e with multiple systems.\n\n```nix\n{ \n  inputs = {\n    git-hooks.url = \"github:cachix/git-hooks.nix\";\n    vimcats.url = \"github:mrcjkb/vimcats\";\n  };\n  \n  outputs = {\n    self,\n    nixpkgs,\n    git-hooks,\n    vimcats,\n    ...\n  }: let\n    system = \"x86_64-linux\";\n    pkgs = nixpkgs.legacyPackages.${system};\n    docgen = final.writeShellApplication {\n      name = \"docgen\";\n      runtimeInputs = [\n        inputs.vimcats.packages.${final.system}.default\n      ];\n      text = ''\n        mkdir -p doc\n        vimcats [args] \u003cpath\u003e \u003e doc/\u003cplugin-name\u003e.txt\n      '';\n    };\n    git-hooks-check = git-hooks.lib.${system}.run {\n      src = self;\n      hooks = {\n        docgen = {\n          enable = true;\n          name = \"docgen\";\n          entry = \"${pkgs.docgen}/bin/docgen\";\n          files = \"\\\\.(lua)$\";\n          pass_filenames = false;\n        };\n      };\n    };\n  in {\n    devShells.${system}.default = {\n      pkgs.mkShell {\n        buildInputs = [\n          docgen\n        ];\n        shellHook = ''\n          # Installs a docgen pre-commit hook\n          ${git-hooks-check.shellHook}\n        '';\n      };\n    };\n    checks.${system} = {\n      inherit git-hooks-check;\n    };\n  };\n}\n```\n\n### Credits\n\n- [lemmy-help](https://github.com/numToStr/lemmy-help)\n- TJ's [docgen](https://github.com/tjdevries/tree-sitter-lua#docgen) module\n- [mini.doc](https://github.com/echasnovski/mini.nvim#minidoc) from `mini.nvim` plugin\n\n\n### License\n\nThis project is [licensed](./LICENSE) according to GPL version 2\nor (at your option) any later version.\n\nlemmy-help (from which this project is forked)\nis [licensed](./lemmy-help-LICENSE) according to MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrcjkb%2Fvimcats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrcjkb%2Fvimcats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrcjkb%2Fvimcats/lists"}