{"id":13895184,"url":"https://github.com/wincent/docvim","last_synced_at":"2025-09-08T03:31:32.961Z","repository":{"id":62435853,"uuid":"54651364","full_name":"wincent/docvim","owner":"wincent","description":"Documentation generator for Vim plug-ins","archived":false,"fork":false,"pushed_at":"2024-07-10T16:00:41.000Z","size":1936,"stargazers_count":25,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-26T22:14:43.183Z","etag":null,"topics":["haskell","vim"],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wincent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2016-03-24T15:09:47.000Z","updated_at":"2024-07-10T15:39:26.000Z","dependencies_parsed_at":"2024-04-16T00:40:12.067Z","dependency_job_id":"188574c5-93ce-4441-bbfc-f9ece0afeade","html_url":"https://github.com/wincent/docvim","commit_stats":{"total_commits":550,"total_committers":2,"mean_commits":275.0,"dds":"0.0072727272727273196","last_synced_commit":"621a4d30f17a9fda64cf6b37d4608cbe08bc72e3"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wincent%2Fdocvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wincent%2Fdocvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wincent%2Fdocvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wincent%2Fdocvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wincent","download_url":"https://codeload.github.com/wincent/docvim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232275423,"owners_count":18498276,"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":["haskell","vim"],"created_at":"2024-08-06T18:02:03.367Z","updated_at":"2025-09-08T03:31:32.700Z","avatar_url":"https://github.com/wincent.png","language":"Haskell","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# docvim: a documentation generator for Neovim plug-ins\n\ndocvim is a documentation generator for Neovim plug-ins, written in Rust, that works by reading \"doc\" comments in Lua files and outputting in multiple formats (text files in `'help'` format and Markdown).\n\ndocvim was formerly a documentation generator for _Vim_ plug-ins, was written in _Haskell_, and worked by parsing _Vimscript_ files. The code for the old version of docvim can be seen on [the `haskell` branch](https://github.com/wincent/docvim/tree/haskell). An even older prototype, never completed, written in JavaScript, can be seen on [the `js` branch](https://github.com/wincent/docvim/tree/js).\n\n\u003e [!WARNING]\n\u003e\n\u003e The following documentation is currently out of date and refers to the old, Haskell version of docvim.\n\n## Quickstart\n\n```bash\n# Print Markdown-formatted help documentation for files in current directory\ndocvim\n\n# Write Markdown README + Neovim help text file for $PLUGIN\ndocvim -c ~/code/$PLUGIN ~/code/$PLUGIN/doc/$PLUGIN.txt ~/code/$PLUGIN/README.md\n```\n\n## Usage\n\n```\ndocvim - a documentation generator for Neovim plug-ins\n\nUsage: docvim [--version] [OUTFILES...] [-d|--debug] [-c|--directory DIRECTORY]\n              [-v|--verbose]\n  Generate documentation for a Neovim plug-in\n\nAvailable options:\n  -h,--help                Show this help text\n  --version                Print version information\n  OUTFILES...              Target file(s) for generated output (default:\n                           standard output)\n  -d,--debug               Print debug information during processing\n  -c,--directory DIRECTORY Change to DIRECTORY before processing (default: \".\")\n  -v,--verbose             Be verbose during processing\n```\n\n## Installation\n\n```\n# Stack:\nstack install docvim\n\n# Cabal:\ncabal update # Do if you see \"Warning: The package list for 'hackage.haskell.org' does not exist.\"\ncabal install\n```\n\n## Syntax\n\n```vim\n\"\"\n\" Docblocks start with a pair of double quotes, followed\n\" by standard Vim comments (with a double quote prefix)\n\" containing Markdown-like text and optional annotations\n\" that look like this:\n\"\n\" ```\n\" @command :Ack {pattern} {options}\n\" ```\n```\n\n### Supported Markdown features\n\n    # Top-level heading\n\n    ## Sub-heading\n\n    --- (Horizontal dividers)\n\n    \u003e Blockquote\n\n    `inline code`\n\n    ```\n    fenced codeblocks (leading space syntax not supported)\n    ```\n\n    ![alt text](http://example.com/image.jpg)\n    (becomes a link in vimdoc, but an image in markdown)\n\n    - Lists.\n\n    Line breaks:\n    \u003cbr\u003e\n    \u003cbr/\u003e\n    \u003cbr /\u003e\n\n### Unsupported Markdown syntax\n\n```\n*foo* (emphasis; turns into Vim doc targets instead)\n\n*,+ (list syntax; just use - instead)\n\n\u003chtml\u003e (we don't want ambiguity with things like \u003cleader\u003e and so on)\n```\n\n### Annotations\n\n- `@command`\n- `@commands`\n- `@dedent`\n- `@footer`\n- `@function`\n- `@functions`\n- `@indent`\n- `@mapping`\n- `@mappings`\n- `@option`\n- `@options`\n- `@plugin`\n\n## Development\n\n### Convenience wrappers\n\n```bash\nbin/accept  # Accept current \"golden\" test output.\nbin/docvim  # Run the docvim executable.\nbin/golden  # Run just the \"golden\" tests.\nbin/haddock # Produce Haddock documentation.\nbin/lint    # Run the linter.\nbin/tasty   # Run just the Tasty tests.\nbin/test    # Run all tests, including lints.\n```\n\nThese are wrappers for the explicit invocations described below.\n\n### Set-up\n\nYou can set-up a development environment using [Stack] (recommended) or [Cabal]:\n\n```bash\n# Stack:\nbrew install stack\nstack build\n\n# Cabal:\nbrew install cabal-install\ncabal sandbox init\ncabal install --only-dependencies --enable-tests\ncabal build\n```\n\n### Running\n\nRun using `stack exec` (or `cabal run`) and passing in docvim-specific `OPTIONS`:\n\n```bash\n# Stack:\nstack exec docvim [OPTIONS]\n\n# Cabal:\ncabal run -- [OPTIONS]\n```\n\nYou can also run the modules from inside the REPL:\n\n```bash\n# Stack:\nstack repl\n\u003e pp \"let l:test=1\" -- pretty-prints AST\n\n# Cabal:\ncabal repl\n\u003e import Text.Docvim.Parse\n\u003e pp \"let l:test=1\" -- pretty-prints AST\n```\n\n### Building\n\n```bash\nstack build --file-watch\n```\n\n### Building and viewing the code-level documentation\n\n```bash\n# Stack:\nstack haddock\nopen .stack-work/dist/x86_64-osx/Cabal-1.22.5.0/doc/html/docvim/index.html\n\n# Cabal:\ncabal haddock --executables\nopen dist/doc/html/docvim/docvim/index.html\n```\n\n### Testing\n\n```bash\n# Stack:\nstack test        # Runs all test suites, including linting.\nstack test :tasty # Runs just the Tasty test suite.\n\n# Cabal:\ncabal test       # Runs all test suites, including linting.\ncabal test tasty # Runs just the Tasty test suite.\n```\n\n#### Updating \"golden\" files\n\n```bash\n# Stack:\nstack test --test-arguments=--accept          # Runs all test suites.\nstack test :tasty --test-arguments=--accept   # Runs just the Tasty test suite.\n\n# Cabal:\ncabal test --test-options=---accept           # Runs all test suites.\ncabal test tasty --test-options=---accept     # Runs just the Tasty test suite.\n```\n\n### Linting\n\n```bash\n# Stack:\nstack test              # Runs linter as part of overall set of suites.\nstack test :hlint       # Runs linter alone.\n\n# Cabal:\ncabal install hlint     # (First-time only).\ncabal test              # Runs linter as part of overall set of suites.\ncabal test hlint        # Runs linter alone.\n\nhlint src               # If you have HLint installed under $PATH.\n```\n\n### Release process\n\n```bash\nvim docvim.cabal # Update version number in two places.\nvim CHANGELOG.md # Update, er, changelog.\ngit commit -p # git tag, git push --follow-tags etc...\nbin/sdist\nbin/upload\n```\n\n## Links\n\n- [Hackage package](https://hackage.haskell.org/package/docvim)\n\n### Examples of plug-ins using docvim\n\n- [Ferret](https://github.com/wincent/ferret)\n- [Loupe](https://github.com/wincent/loupe)\n- [Pinnacle](https://github.com/wincent/pinnacle)\n- [Scalpel](https://github.com/wincent/scalpel)\n- [vim-docvim](https://github.com/wincent/vim-docvim)\n\n## FAQ\n\n### Why a new tool and not an existing one like [Vimdoc]?\n\n* I wanted to target multiple output formats (Vim help files and Markdown).\n* I wanted total control over the presentation of the output.\n* It's fun to build new things from scratch.\n* The project is a great fit for my learn-me-a-Haskell goal this year.\n\n### Why is it called \"docvim\"?\n\n\"Vimdoc\" was the first name that occurred to me when I started this project, but:\n\n* The number one hit for \"vimdoc\" is [this online copy of Vim's own documentation](http://vimdoc.sourceforge.net/).\n* The name \"Vimdoc\" is already taken by [a similar project](https://github.com/google/vimdoc).\n\nSo, in a remarkable flash of profound creativity, I settled on \"docvim\" instead, which right now yields this pleasing search result:\n\n\u003e Did you mean: dacvim\n\n[Cabal]: https://www.haskell.org/cabal/\n[Stack]: http://haskellstack.org/\n[Vimdoc]: https://github.com/google/vimdoc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwincent%2Fdocvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwincent%2Fdocvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwincent%2Fdocvim/lists"}